Media Picker

In order to select items from your Media Library, the packages provides a custom Filament form field called MediaPicker. This field can be used in any Filament form, both inside or outside a Filament panel.

The field consists of two parts: first, when you have items selected, it will display them in your form. Second, it provides a modal to open when the users wants to select or upload items to the media library.

Using the field

You can include the field like this:

MediaPicker::make('image')
    ->label('Choose image')
    ->required()

Depending on which driver you are using, the value of the field will be either the id of the MediaLibraryItem (if you are using the medialibrary driver) or the file path (if you are using the filesystem driver).

Selecting multiple files

To select multiple files, you can use the ->multiple() method:

MediaPicker::make('images')
    ->label('Choose images')
    ->multiple()
    ->required()

If you are storing the keys as an JSON array on your model, you will need to add an array or collection cast to the field in your model.

Minimum or maximum files

You can require a minimum or maximum number of files to be selected using the ->minFiles() and ->maxFiles() methods:

MediaPicker::make('images')
    ->label('Select between 2-5 files for your header gallery')
    ->multiple()
    ->minFiles(2)
    ->maxFiles(5)
    // Optional, override custom validation message: 
    ->validationMessages([
        'min' => 'Please select at least 2 brochures.',
        'max' => 'Please select maximum 5 brochures.',
    ])

Limiting file types

You can limit the file types the user can select using the ->acceptedFileTypes() method:

MediaPicker::make('documents')
    ->label('Choose documents')
    ->multiple()
    ->acceptedFileTypes(['application/pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'])
    ->required()

Please note that this will only limit the selection of files in the media picker. It will not prevent users from uploading other file types to the media library itself. If you would like to prevent that, please look into defining upload constraints.

If you would like to provide a custom validation message, you can use the ->validationMessages() function:

MediaPicker::make('brochure_id')
    ->label('Choose brochure')
    ->acceptedFileTypes(['application/pdf'])
    // Optional, override custom validation message: 
    ->validationMessages([
        'accepted_file_types' => 'Brochures can only be PDFs.',
    ])

Modifying the select action

To modify the select action that opens the Media Picker modal, you can use the following methods:

MediaPicker::make('image')
    ->label('Choose image')
    ->selectMediaActionLabel('Select image')
    ->selectMediaActionColor('primary') 
    ->selectMediaActionIcon(Heroicon::OutlinedPlus) 
    ->modifySelectMediaActionIcon(function (SelectMediaAction $action) {
        // ...
    }) 

Modal

You can also customize the modal that opens when selecting media.

Scoping to folder

By default, the MediaPicker will open in the root folder. However, in some cases, you might want to only allow your users to select/upload images from and to specific folders. You can do that using the ->scopedFolder() function. This forces a specific folder to allow your users to create and select from (e.g. go down in hierarchy), but not to open up parent folders or go up in the hierarchy.

To scope the Media Picker to a specific folder, you can use the ->scopedFolder() method:

use RalphJSmit\Filament\Explore\Filament\MediaLibrary\MediaLibraryFolder;

MediaPicker::make('featured_image_id')
    ->scopedFolder(MediaLibraryFolder::find(99)),

Using a closure:

MediaPicker::make('featured_image_id')
    ->folder(fn (Event $record) => $record->mediaLibraryFolder),

To use this method with the Storage/disk driver, you can provide a FileData object instead of a MediaLibraryFolder object:

use RalphJSmit\Filament\Explore\Drivers\FilesystemStorageDriver\FileData;
use RalphJSmit\Filament\Explore\Enums\FileType;

MediaPicker::make('featured_image_path')
    ->scopedFolder(FileData::fromDisk('s3', 'path/to/folder', FileType::Folder)),

Default folder

If you don't want to force your users to use a specific folder, but only nudge them, you can also use the ->defaultFolder() method. This method allows you to specify a default folder that the MediaPicker will open in. The difference with ->folder() is that this method will allow your users to open other folders as well, also higher in the hierarchy.

The defaultFolder() functions accepts a MediaLibraryFolder or FileData object as parameter. You can also pass a closure, and use that closure to retrieve the folder dynamically from e.g. the current record.

use RalphJSmit\Filament\Explore\Drivers\FilesystemStorageDriver\FileData;
use RalphJSmit\Filament\Explore\Enums\FileType;

MediaPicker::make('featured_image_path')
    ->defaultFolder(FileData::fromDisk('s3', 'path/to/folder', FileType::Folder)),

Using a closure:

MediaPicker::make('featured_image_path')
    ->defaultFolder(fn (Event $record) => FileData::fromDisk('s3', "events/{$record->getKey()}", FileType::Folder)),

Note: please note that the media picker will now open this folder by default. However, users are still able to click to other folders and view them. If you have a need to disable this and only force a specific folder, please use the ->scopedFolder() method (see above).

Individual file info on multiple selection

By default, when a user is allowed to select one file, the modal with open the Media Library including the file-info sidebar at the right. When the user is allowed to select multiple files, the sidebar will not be shown by default as that can be confusing to the user. However, if you still wish to enable this, you can use the ->fileInfoMultipleFileSelection() method:

MediaPicker::make('images')
    ->label('Choose images')
    ->multiple()
    ->fileInfoMultipleFileSelection()                           

This will enable both the bulk-selection checkboxes as well as the file-info sidebar when selecting multiple files.

MediaPicker::make('featured_image_id')
    ->folder(MediaLibraryFolder::find(99)),

Using a closure:

MediaPicker::make('featured_image_id')
    ->folder(fn (Event $record) => $record->mediaLibraryFolder),

Selected items

Reordering

You can allow your users to reorder the selected items using the ->reorderable() method:

MediaPicker::make('images')
    ->label('Choose images')
    ->multiple()
    ->reorderable()
    ->required()

If a user hovers over an image, the cursor will change into a “move” icon, so that it is clear that the media can be reordered.

Downloading

You can allow your users to download the selected items using the ->downloadable() method:

MediaPicker::make('image')
    ->label('Featured image')
    ->downloadable()

Actions

You can add additional actions to each selected item using the ->fileActions() method:

use RalphJSmit\Filament\Explore\Filament\Actions\RenameAction;

MediaPicker::make('images')
    ->label('Choose images')
    ->multiple()
    ->fileActions([
        RenameAction::make(),
        Action::make('optimize')
            ->icon(Heroicon::OutlinedSparkles)
            ->action(function (MediaLibraryItem $file) {
                // Perform an action...
            }),
    ])

This will display the actions together with the download and/or delete action.

Bulk actions

You can allow your users to perform bulk actions on the selected items in your field. This is very handy to let the user batch-process an already selected set of files,

To enable bulk selection & actions, use the ->bulkSelectable() method:

use RalphJSmit\Filament\Explore\Filament\Actions\BulkAction;

MediaPicker::make('images')
    ->label('Choose images')
    ->multiple()
    ->bulkSelectable()
    ->bulkActions([
        BulkAction::make('optimize')
            ->icon(Heroicon::OutlinedSparkles)
            ->action(function (Collection $files) {
                // Perform an action...
            }),
    ])

Relationship support

This only applies when using the Media Library Item Driver.

You can integrate the MediaPicker with a BelongsTo or BelongsToMany relationship on your model. This is useful when you want to store the relationship between your model and media library items in a proper database relationship instead of storing IDs directly in a column.

The MediaPicker supports both relationship types:

• BelongsTo: For single media library items
• BelongsToMany: For multiple media library items

To integrate a relationship, follow the steps below:

php artisan make:migration create_post_media_library_item_table

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('media_library_item_post', function (Blueprint $table) {
            $table->id();
            $table->foreignId('post_id')->constrained()->cascadeOnDelete();
            $table->foreignId('media_library_item_id')->constrained()->cascadeOnDelete();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('media_library_item_post');
    }
};

php artisan migrate

use RalphJSmit\Filament\MediaLibrary\Models\MediaLibraryItem;

class Post extends Model
{
    public function featuredImage(): BelongsTo
    {
        return $this->belongsTo(MediaLibraryItem::class, 'featured_image_id');
    }
}

use RalphJSmit\Filament\MediaLibrary\Models\MediaLibraryItem;

class Post extends Model
{
    public function images(): BelongsToMany
    {
        return $this->belongsToMany(MediaLibraryItem::class);
    }
}

public function images(): BelongsToMany
{
    return $this->belongsToMany(
        MediaLibraryItem::class,
        'post_media_library_item'
    );
}

MediaPicker::make('featuredImage')
    ->label('Featured image')
    ->relationship('featuredImage')
    ->required()

MediaPicker::make('images')
    ->label('Gallery images')
    ->relationship('images')
    ->multiple()
    ->required()