README

A Filament plugin that adds a file picker button to the RichEditor toolbar, powered by Livewire Filemanager.

Users can browse, search, and insert files directly from the RichEditor. Images are inserted as <img> tags, other files as download links.

Requirements

• PHP 8.2+
• Filament 4.x or 5.x
• livewire-filemanager/filemanager ^1.0 (with API enabled)
• Laravel Sanctum (the filemanager API uses auth:sanctum)

Installation

1. Install the package

composer require livewire-filemanager/filament-plugin

The service provider is auto-discovered. No manual registration needed.

2. Install Laravel Sanctum

The filemanager API routes are protected by the auth:sanctum guard. If Sanctum is not already installed in your project:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

Note: Filament uses cookie-based session authentication. Sanctum's stateful authentication works out of the box with Filament sessions — no API tokens needed. Just make sure your domain is listed in SANCTUM_STATEFUL_DOMAINS in your .env if you're using a custom domain:

SANCTUM_STATEFUL_DOMAINS=filament.test

3. Publish the config (optional)

php artisan vendor:publish --tag=filemanager-filament-config

This creates config/filemanager-filament.php:

return [
    'api_url' => env('FILEMANAGER_API_URL', '/api/filemanager/v1'),
    'lang' => env('FILEMANAGER_LANG', 'en'),
    'toolbar_label' => 'Files',
];

Usage

Register the plugin in your Panel

use LivewireFilemanager\Filament\FilemanagerPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            // ...
            ->plugins([
                FilemanagerPlugin::make(),
            ]);
    }
}

Add it to a RichEditor field

use LivewireFilemanager\Filament\FilemanagerPlugin;

RichEditor::make('content')
    ->plugins([
        FilemanagerPlugin::make(),
    ])

A "Files" button appears in the toolbar. Clicking it (or pressing Ctrl+Shift+F / Cmd+Shift+F) opens the file browser modal.

Full-page filemanager

You can also add a dedicated filemanager page to your panel. Create a Filament page:

// app/Filament/Pages/Filemanager.php
<?php

namespace App\Filament\Pages;

use BackedEnum;
use Filament\Pages\Page;
use Filament\Support\Icons\Heroicon;

class Filemanager extends Page
{
    protected string $view = 'filament.pages.filemanager';

    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedFolderOpen;

    protected static ?string $navigationLabel = 'Filemanager';

    protected static ?string $title = 'Filemanager';

    protected static ?string $slug = 'filemanager';
}

Then create the Blade view:

{{-- resources/views/filament/pages/filemanager.blade.php --}}
@push('styles')
    @filemanagerStyles
@endpush

@push('scripts')
    @filemanagerScripts
@endpush

<x-filament-panels::page>
    <div class="h-[calc(100vh-12rem)] rounded-xl overflow-hidden border border-gray-200 dark:border-gray-700">
        <livewire:livewire-filemanager />
    </div>
</x-filament-panels::page>

Note: @filemanagerStyles loads Tailwind via CDN, which is fine for development. For production, create a custom Filament theme and add the package views to the Tailwind content scan:

/* Tailwind v4 (resources/css/filament/admin/theme.css) */
@source '../../../../vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php';

// Tailwind v3 (tailwind.config.js)
content: [
    './vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php',
]

Sanctum & session configuration

The filemanager API uses auth:sanctum. Since Filament authenticates via cookies (session-based), you need to configure Sanctum for stateful requests.

1. Set your domain in .env:

SESSION_DOMAIN=filament.test
SANCTUM_STATEFUL_DOMAINS=filament.test

2. Use the web middleware for API routes so session cookies are processed.

Publish the filemanager config if not already done:

php artisan vendor:publish --tag=livewire-filemanager-config

Then in config/livewire-filemanager.php, change api to web:

'api' => [
    'enabled' => true,
    'middleware' => ['web', 'auth:sanctum'],  // 'web' instead of 'api'
    // ...
],

Why web instead of api? Filament uses session-based authentication. The api middleware group doesn't process session cookies, so Sanctum can't identify the logged-in user. Switching to web ensures the session cookie is read and the user is authenticated transparently.

Configuration

Via config file / environment

Via fluent API (per-panel override)

FilemanagerPlugin::make()
    ->apiUrl('/custom/api/endpoint')
    ->lang('fr')
    ->toolbarLabel('Fichiers')

How it works

FilemanagerPlugin::boot()
  -> FilamentAsset::registerScriptData()    # injects apiUrl + lang into window.filamentData
  -> getTipTapJsExtensions()               # registers the JS bundle URL

RichEditor loads the extension via dynamic import()
  -> export default factory function        # reads window.filamentData
  -> Filemanager.configure({ apiUrl, lang })  # configures the TipTap extension

User clicks toolbar button
  -> editor().commands.openFilemanager()    # opens the modal
  -> modal fetches files from API           # browse, search, select
  -> inserts <img> or <a> into editor       # done

Troubleshooting

Auth guard [sanctum] is not defined

Laravel Sanctum is not installed. See the installation steps above.

The "Files" button doesn't appear

Make sure the plugin is registered in both places:

1. In AdminPanelProvider via ->plugins([FilemanagerPlugin::make()])
2. On the RichEditor field via ->plugins([FilemanagerPlugin::make()])

API returns 401 Unauthorized / Route [login] not defined

The filemanager API uses auth:sanctum with session cookies. Ensure:

1. Your domain is in SANCTUM_STATEFUL_DOMAINS in .env
2. SESSION_DOMAIN is set to your domain in .env
3. The filemanager API middleware is set to ['web', 'auth:sanctum'] (not ['api', ...]) — see Sanctum & session configuration
4. The user is logged into Filament

Modal opens but no files are shown

The backend package livewire-filemanager/filemanager must be installed and configured:

composer require livewire-filemanager/filemanager
php artisan vendor:publish --tag=livewire-filemanager-config
php artisan vendor:publish --tag=livewire-filemanager-migrations
php artisan migrate

Make sure the API is enabled in config/livewire-filemanager.php:

'api' => [
    'enabled' => true,
    'middleware' => ['web', 'auth:sanctum'],
],

Filemanager page has no styles

The Livewire filemanager uses Tailwind utility classes. If styles are missing, add @filemanagerStyles to inject the Tailwind CDN (dev only), or set up a custom Filament theme that scans the package views.

Alpine Warning: missing ui plugin

Add @filemanagerScripts to your page view — it loads the @alpinejs/ui plugin required by the filemanager's dialog and popover components.

Development

Building the JS bundle

npm install
npm run build

This bundles resources/js/src/index.ts into resources/js/dist/filemanager.js using esbuild.

Running tests

composer install
vendor/bin/pest

License

MIT