[Bug]: How to properly register a custom Editor.js tool (MathLive / MathBlock)?

[malhanafi]

What happened?

Hello 👋
First of all, thank you for this great package — it works very well for standard Editor.js tools.

I’m trying to integrate a custom Editor.js tool based on MathLive (a MathBlock for LaTeX equations), but I’m currently unable to make it appear or register correctly, and I would really appreciate your guidance.

What I’m trying to achieve

• Add a custom Editor.js tool (MathBlock using MathLive)
• Tool key: math
• Use it alongside other tools like header, list, quote, etc.

What I’ve done so far

in filament panel provider i do

            ->assets([
                Js::make('mathlive-js', 'https://cdn.jsdelivr.net/npm/mathlive@latest/dist/mathlive.min.js'),
                Js::make('editorjs-math-block-js', asset('js/editorjs-math-block.js?' . time())),
            ])

js/editorjs-math-block.js

class MathBlock {
    static get toolbox() {
        return {
            title: 'Equation',
            icon: '∑',
        };
    }

    constructor({data}) {
        this.data = data || {latex: ''};
        this.wrapper = document.createElement('div');
    }

    render() {
        const math = document.createElement('math-field');
        math.value = this.data.latex || 'x^2';
        math.setAttribute('dir', 'ltr');

        this.wrapper.appendChild(math);
        this.mathField = math;

        return this.wrapper;
    }

    save() {
        return {
            latex: this.mathField.value,
        };
    }
}

window.MathBlock = MathBlock;

Installed MathLive and my custom MathBlock JS file (confirmed it loads correctly):

• console.log(window.editorjs); //undefined
• console.log(window.MathLive); // defined
• console.log(window.MathBlock); // class exists, toolbox getter exists

And I've added the tool to the Filament EditorJS config:

'profiles' => [
    'math' => [
        'header',
        'math',
        'list',
        'quote',
        'table',
    ],
],

Used the profile in my form field:

            EditorjsTextField::make('question')
                ->translateLabel()
                ->columnSpanFull()
                ->tools('math')
                ->required(),

The editor loads normally, and all other tools appear, but the math tool does not appear in the toolbar.

What I tried to debug

• Inspecting the DOM and JS runtime
• Trying to access the Editor.js instance from the DOM (e.g. __editorjs)
• Waiting for initialization / polling
• Livewire hooks

However, it seems that:

• The Editor.js instance is not exposed
• Only tool names (strings) are supported
• There’s no documented way to register custom JS tools

My question

What is the correct / supported way to register a custom Editor.js tool (JS class) with this package?

Specifically:

• Is it currently supported?
• If yes, how should the JS tool be registered?
• If not, is there a recommended extension point or planned support?

Thank you again for your work on this package.

How to reproduce the bug

JS packages will be loaded but doesn't appear in the editor

Package Version

^1.1

PHP Version

8.4

Laravel Version

^12.42.0

Which operating systems does with happen with?

Linux

Notes

No response

[athphane]

Hi @malhanafi ! Registering custom blocks is possible. It's a bit of work but it does work.

I have not tried to 'make' my own Block yet. I usually use blocks made by other people. I'd imagine that making the Block is a whole thing of it's own.

There are a couple of steps to getting a custom Block registered for the EditorJS editor. I will take the example of @editorjs/link custom block. Make sure to update to the latest version of the package before you do all of this. I was just now adding a bunch of extra blocks using this same method so I know it works.

1. Ensure that you are able to add a custom JS file to the Filament HEAD. Do something like this.

// app/Providers/AppServiceProvider

FilamentView::registerRenderHook(
    PanelsRenderHook::HEAD_END,
    fn (): string => Blade::render('@vite(\'resources/js/filament-app.js\')'),
);

2. Create the associated JS file from step 1. Ideally keep the editorjs custom config in its own file for clean code.

// resources/js/filament-app.js

import './bootstrap.js';

import './filament-editorjs-extensions.js'

3. Import the necessary library for your custom block, add then add it to the window.filamentEditorJsTools

// resources/js/filament-editorjs-extensions.js

import LinkTool from '@editorjs/link'

window.filamentEditorJsTools = window.filamentEditorJsTools || {}

// Link Preview plugin
window.filamentEditorJsTools.link_preview = LinkTool

That is it for the JS side. Now for the PHP side.

4. To use it, you must add it as a plugin to the EditorJsTextField in your Filament Resource Form Schema. EG:

EditorjsTextField::make('content')
    ->columnSpanFull()
    ->addPlugin('link_preview', [
        'foo' => 'bar',
    ])

The first param of the addPlugin method needs the same name as how you defined it in the JS.
For example, window.filamentEditorJsTools.link_preview means you pass in link_preview to the addPlugin method. Any extra config you want to pass in from PHP to JS can be given in the second param as an array.

Follow these steps and let me know how it goes. It should work nicely.

Sorry for the late reply 😅