Configuration

Publish the file with php artisan vendor:publish --tag=filament-media-library-config, or run php artisan media-library:install. The config lives at config/filament-media-library.php.

Inside a Filament panel, the fluent options on the plugin override features, browser, upload.accepted_mime_types, upload.max_file_size, upload.duplicates and tenancy. Outside panels, this file is the only place to set them.

Models and tables

Key	Type	Default	What it does
models.item	class-string	MediaItem::class	The model for library files. Swap it to extend the built-in model.
models.folder	class-string	MediaFolder::class	The folder model.
models.tag	class-string	MediaTag::class	The tag model.
models.attachment	class-string	MediaAttachment::class	The pivot model that records where a file is used.
table_prefix	string	'media_library_'	Prefix for the library tables.
user_model	class-string or null	null	The model for uploaders and owners. null uses your auth provider's model.

Key types

Set these before you run the migration.

Key	Type	Default	What it does
key_types.user	int, uuid, ulid or string	'int'	Column type for uploaded_by and created_by.
key_types.tenant	same	'int'	Column type for the tenant foreign key. See Multi-tenancy.
key_types.attachable	same	'int'	Column type for the model that uses a file.

Disk

Key	Type	Default	What it does
disk	string	env('MEDIA_LIBRARY_DISK', env('MEDIA_DISK', 'public'))	The disk that holds originals.
conversions_disk	string or null	null	A separate disk for thumbnails and conversions. null keeps them with the original.
temporary_url_minutes	int	30	Lifetime of temporary URLs (S3) and signed streaming links (local) for files on a private disk.
route_prefix	string	'media-library'	URL prefix for the upload, download and serve routes.

See Storage & S3.

Upload

Key	Type	Default	What it does
upload.max_file_size	int (kilobytes)	512 * 1024	Largest file, 512 MB by default. 0 removes the limit.
upload.chunk_size	int (bytes)	5 * 1024 * 1024	Size of each chunk the browser sends. The server never accepts a value under 256 KB.
upload.max_parallel_uploads	int	3	Files the browser uploads at the same time.
upload.accepted_mime_types	array	images, video, audio, PDF, ZIP, text, CSV, Office documents	MIME patterns the library accepts. image/* style wildcards work.
upload.blocked_extensions	array	scripts, executables, html, xml, js and similar	Extensions that are always refused, whatever the MIME type says.
upload.sanitize_svg	bool	true	Strip scripts and unsafe markup from SVG uploads.
upload.preserve_file_names	bool	false	Keep the original file name on disk instead of a generated one.
upload.duplicates	DuplicateStrategy	DuplicateStrategy::Ask	What happens when a file matches an existing one by hash. Ask, Allow or UseExisting.
upload.url_import	bool	true	Allow importing files from a URL. The url_import feature overrides it.
upload.chunk_directory	string	'media-library-chunks'	Folder under storage/app for unfinished chunks.

See Uploading and Security.

Conversions

conversions is an array keyed by conversion name. The defaults:

'conversions' => [
    'thumb' => ['width' => 480, 'height' => 480, 'fit' => 'crop', 'format' => 'webp', 'queued' => false],
    'preview' => ['width' => 1600, 'height' => 1600, 'fit' => 'contain', 'format' => 'webp', 'queued' => true, 'responsive' => true, 'optimize' => true],
],

Option	Type	What it does
width, height	int	Target size in pixels.
fit	string	crop, contain and the other Spatie fit modes. Cropped conversions follow the focal point.
format	string	Output format, for example webp.
queued	bool	Generate on the queue. thumb is synchronous so new uploads appear at once.
responsive	bool	Generate responsive image variants.
optimize	bool	Run Spatie's image optimizers. Slow, so queue it.

Add your own names to use them with <x-media-library-image> and the table columns.

Versions

Key	Type	Default	What it does
versions.enabled	bool	true	Keep the previous file when you replace or save an edit as a new version.
versions.keep	int	10	Versions kept per file. Older ones are pruned.

Tenancy

Key	Type	Default	What it does
tenancy.enabled	bool	false	Scope the library to a tenant outside panels. Panels with tenancy do this on their own.
tenancy.resolver	class-string	FilamentTenantResolver::class	The class that returns the current tenant. StanclTenantResolver ships with the package.
tenancy.strict	bool	true	Show nothing when no tenant resolves.

See Multi-tenancy.

Private media

Key	Type	Default	What it does
private_media	bool	true	Let uploaders mark files and folders private. Private records are visible to their owner and to users who pass viewPrivate.

See Private files and Authorization.

Quota

Key	Type	Default	What it does
quota	int, null or invokable class-string	null	Maximum bytes per tenant, or for the whole app without tenancy. An invokable class receives the current tenant and returns bytes or null.

Trash

Key	Type	Default	What it does
trash.enabled	bool	true	Move deleted files to the trash. When off, deleting removes the file for good.
trash.prune_after_days	int	30	Age at which media-library:prune removes trashed files.

Alt text

Key	Type	Default	What it does
alt_text.generator	class-string	NullAltTextGenerator::class	Class that writes alt text. Use AnthropicAltTextGenerator::class for Claude, or your own AltTextGenerator.
alt_text.auto_generate	bool	false	Describe every new image on the queue.
alt_text.anthropic.api_key	string	env('ANTHROPIC_API_KEY')	API key for AnthropicAltTextGenerator.
alt_text.anthropic.model	string	env('MEDIA_LIBRARY_ALT_TEXT_MODEL', 'claude-opus-5-5')	Model used for descriptions.

See AI alt text.

Browser

Key	Type	Default	What it does
browser.per_page	int	48	Items loaded per page.
browser.default_layout	'grid' or 'list'	'grid'	Starting layout.
browser.default_sort	string	'newest'	Starting sort: newest, oldest, name_asc, name_desc, largest, smallest.
browser.tile_size	int	180	Grid tile size in pixels. The plugin clamps it between 120 and 280.

Features

Each key switches one part of the library on or off. null keeps the default, which is on. The four keys that default to null also honour their older config key (trash.enabled, private_media, versions.enabled, upload.url_import).

Key	Default
features.folders, tags, favorites	true
features.trash	null
features.private_media	null
features.versions	null
features.image_editor, focal_point	true
features.url_import	null
features.folder_upload, alt_text, duplicate, download, exif, usage, smart_views, keyboard_shortcuts	true

The plugin lists what each flag turns off.

Standalone

Key	Type	Default	What it does
standalone.enabled	bool	false	Allow the picker and library on your own Livewire and Blade pages. When off, the standalone routes return 404.
standalone.middleware	array	['web', 'auth']	Middleware for the standalone upload and download routes.

Read Outside Filament panels before you turn this on. The default policy lets every signed-in user manage shared media, so register your own policy first on a site with customer accounts.