README

This package embeds the BlockNote rich-text editor in Filament forms, using a bundled React UI (BlockNote + Mantine), and persists document state as a JSON string of BlockNote blocks.

Composer package: weave-php/blocknote-filament · PHP namespace: Weave\BlockNote\... (unchanged on purpose so imports stay stable).

Requirements

• PHP ^8.3
• Laravel 11+ (as required by your Filament version)
• Filament ^3.0 || ^4.0 || ^5.0 (via filament/filament)

Installation

composer require weave-php/blocknote-filament

Laravel auto-discovers Weave\BlockNote\BlockNoteServiceProvider.

Register the plugin on any panel (optional but recommended for consistency with Filament’s plugin API):

use Filament\Panel;
use Weave\BlockNote\Filament\BlockNotePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        ->plugin(BlockNotePlugin::make());
}

Assets are registered globally by the service provider; the plugin is mainly an explicit hook for panel configuration.

Publish Filament assets

After install or upgrade, publish JS/CSS to public/:

php artisan filament:assets

Files are published under public/js/weave-php/blocknote-filament/ and public/css/weave-php/blocknote-filament/.

The editor loads Inter from Filament’s font bundle (public/fonts/filament/filament/inter/). Run filament:assets or filament:install so that path exists.

Configuration

Publish the config file if you want to customize uploads and the upload route:

php artisan vendor:publish --tag=weave-blocknote-config

Default configuration:

<?php

return [

    'uploads' => [
        'enabled' => env('WEAVE_BLOCKNOTE_UPLOADS_ENABLED', true),

        'disk' => env('WEAVE_BLOCKNOTE_UPLOADS_DISK', 'public'),

        'directory' => env('WEAVE_BLOCKNOTE_UPLOADS_DIRECTORY', 'blocknote'),

        'visibility' => env('WEAVE_BLOCKNOTE_UPLOADS_VISIBILITY', 'public'),

        'max_size_kb' => (int) env('WEAVE_BLOCKNOTE_UPLOADS_MAX_KB', 12_288),

        'middleware' => ['web', 'auth'],

        'throttle' => env('WEAVE_BLOCKNOTE_UPLOADS_THROTTLE', '60,1'),

        'authorize' => null,

        'response_url_key' => 'url',

        'input_name' => 'file',
    ],

];

Configuration options:

Usage

Add BlockNoteEditor to a form schema. State is a JSON string (BlockNote document).

use Filament\Schemas\Schema;
use Weave\BlockNote\Forms\Components\BlockNoteEditor;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        BlockNoteEditor::make('contents')
            ->label('Content')
            ->default('[]')
            ->minHeight(480)
            ->fullscreenButton()
            ->columnSpanFull(),
    ]);
}

Persist as longText or json in your migration.

Field API

Standard Filament field methods (label(), required(), rules(), columnSpanFull(), …) apply.

Uploads & custom storage

Default route: POST /weave-blocknote/upload (weave-blocknote.upload). Implement Weave\BlockNote\Contracts\StoresBlockNoteUploads and bind it in a service provider to use S3 or another backend; return a public URL string.

The bundled script sends Accept: application/json, credentials: 'same-origin', and CSRF headers when available.

Block types, localization, validation

• Restrict blocks with ->withoutBlocks([...]) or ->blocks([...]).
• Locale: ->blockNoteLocale('fr') or rely on app()->getLocale() (BlockNote locales).
• Validation: Weave\BlockNote\Rules\BlockNoteDocumentRule — messages use weave-blocknote::validation.blocknote_document.* (override under lang/vendor/weave-blocknote/{locale}/validation.php).

Tables & infolist

Plain-text preview helpers:

use Weave\BlockNote\Tables\Columns\BlockNoteColumn;
use Weave\BlockNote\Infolists\Components\BlockNoteEntry;

BlockNoteColumn::make('contents');
BlockNoteEntry::make('contents');

Weave\BlockNote\Support\BlockNoteDocument::toPlainText() extracts preview text from JSON.

Livewire & theming

The editor mount uses wire:ignore. Avoid replacing the field’s DOM subtree blindly. With Filament SPA / wire:navigate, full page loads may be more reliable if the editor fails to mount after navigation.

BlockNote uses Mantine inside the bundle; it does not automatically match Filament theme tokens or dark mode. Target .weave-blocknote-shell for custom CSS if needed.

Translations

Namespace: weave-blocknote (e.g. weave-blocknote::editor.enter_fullscreen, weave-blocknote::validation.blocknote_document.must_be_string). Override via lang/vendor/weave-blocknote/{locale}/ in your app.

Development (this package)

cd vendor/weave-php/blocknote-filament   # or clone
npm install
npm run build

Outputs dist/blocknote-editor.js and dist/blocknote-editor.css (esbuild). Commit dist/ if you ship prebuilt assets, then run php artisan filament:assets in consuming apps.

Stack: React 19, @blocknote/mantine, esbuild.

Credits

Weave PHP

License

MIT. See LICENSE.md.