Menu Builder by Ngô Quốc Đạt

• Requirements
• Upgrading
  • From v0.7.x (Filament v3) to v1.x (Filament v5)
• Installation
• Usage
  • Locations
  • Menu Panels
    • Model Panel
    • Static Panel
  • Custom Link & Custom Text Panels
  • Custom Fields
  • Customizing Navigation
  • Indent / Unindent
  • Maximum Depth
  • Translatable Menus
    • Setup
    • Configuring Translatable Fields
    • Rendering Translated Titles
    • Spatie Translatable Compatibility
  • Custom Models
  • Rendering Menus
    • Active State Detection
  • MenuItem Properties
• Testing
• Changelog
• License

A Filament plugin for building menus with drag-and-drop ordering, nesting, custom links, and dynamic panels.

#Requirements

• PHP 8.3+
• Filament 5.0+
• Laravel 12+

#Upgrading

#From v0.7.x (Filament v3) to v1.x (Filament v5)

1. Update your composer.json:

composer require datlechin/filament-menu-builder:^1.0

2. Publish and run the new migration to add the panel, icon, and classes columns:

php artisan vendor:publish --tag="filament-menu-builder-migrations"
php artisan migrate

The upgrade migration checks for existing columns before adding them, so it's safe on fresh installs too.

3. Re-publish the config file if you published it previously:

php artisan vendor:publish --tag="filament-menu-builder-config" --force

#Installation

Install via Composer:

composer require datlechin/filament-menu-builder

Publish and run the migrations:

php artisan vendor:publish --tag="filament-menu-builder-migrations"
php artisan migrate

Optionally, publish the config file:

php artisan vendor:publish --tag="filament-menu-builder-config"

Or use the install command:

php artisan filament-menu-builder:install

You will need to set up a Filament custom theme

If you don't yet have a custom theme, run the following command:

php artisan make:filament-theme

Next, open up the theme.css file for the custom theme and add the following line:

@import "../../../../vendor/datlechin/filament-menu-builder/resources/css/index.css";
@source "../../../../vendor/datlechin/filament-menu-builder/resources/**/*.blade.php";

#Usage

Register the plugin in your panel provider:

use Datlechin\FilamentMenuBuilder\FilamentMenuBuilderPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentMenuBuilderPlugin::make(),
        ]);
}

#Locations

Locations define where menus appear in your application:

FilamentMenuBuilderPlugin::make()
    ->addLocations([
        'header' => 'Header',
        'footer' => 'Footer',
    ])

#Menu Panels

Panels provide item sources for menus, either from Eloquent models or static lists.

#Model Panel

Implement MenuPanelable on your model:

use Datlechin\FilamentMenuBuilder\Contracts\MenuPanelable;

class Page extends Model implements MenuPanelable
{
    public function getMenuPanelTitle(): string
    {
        return $this->title;
    }

    public function getMenuPanelUrl(): string
    {
        return route('pages.show', $this);
    }

    public function getMenuPanelName(): string
    {
        return 'Pages';
    }
}

Then register it:

use Datlechin\FilamentMenuBuilder\MenuPanel\ModelMenuPanel;

FilamentMenuBuilderPlugin::make()
    ->addMenuPanels([
        ModelMenuPanel::make()
            ->model(Page::class),
    ])

#Static Panel

use Datlechin\FilamentMenuBuilder\MenuPanel\StaticMenuPanel;

FilamentMenuBuilderPlugin::make()
    ->addMenuPanels([
        StaticMenuPanel::make()
            ->name('pages')
            ->add('Home', '/')
            ->add('About', '/about')
            ->add('Contact', '/contact'),
    ])

add() also accepts target, icon, and classes:

StaticMenuPanel::make()
    ->name('social')
    ->add('GitHub', 'https://github.com', target: '_blank', icon: 'heroicon-o-code-bracket')
    ->add('Twitter', 'https://twitter.com', target: '_blank', classes: 'text-blue-500')

#Custom Link & Custom Text Panels

The custom link panel is shown by default. The custom text panel (for non-link items like headings) is opt-in:

FilamentMenuBuilderPlugin::make()
    ->showCustomLinkPanel(true)
    ->showCustomTextPanel(true)

#Custom Fields

Add extra fields to the menu or menu item forms:

use Filament\Forms\Components\TextInput;

FilamentMenuBuilderPlugin::make()
    ->addMenuFields([
        TextInput::make('description'),
    ])
    ->addMenuItemFields([
        TextInput::make('badge'),
    ])

Singular methods work too:

FilamentMenuBuilderPlugin::make()
    ->addMenuField(TextInput::make('description'))
    ->addMenuItemField(TextInput::make('badge'))

Multiple calls are merged, so fields registered from different service providers won't overwrite each other.

#Customizing Navigation

FilamentMenuBuilderPlugin::make()
    ->navigationLabel('Menus')
    ->navigationGroup('Content')
    ->navigationIcon('heroicon-o-bars-3')
    ->navigationSort(3)
    ->navigationCountBadge(true)

#Indent / Unindent

Nesting via indent/unindent actions is enabled by default:

FilamentMenuBuilderPlugin::make()
    ->enableIndentActions(true)

#Maximum Depth

By default, menu items can be nested indefinitely. Use maxDepth() to limit how deep items may be nested, both through the indent action and drag and drop. Depth is zero-based: root items have a depth of 0, so maxDepth(0) keeps a menu flat and maxDepth(2) allows up to three levels.

FilamentMenuBuilderPlugin::make()
    ->maxDepth(2)

Pass a closure to use a different limit per menu. The closure receives the $menu being edited:

use Datlechin\FilamentMenuBuilder\Models\Menu;

FilamentMenuBuilderPlugin::make()
    ->maxDepth(fn (Menu $menu): ?int => $menu->locations()->where('location', 'footer')->exists() ? 0 : 2)

Moving an item also moves its children, so a move is only allowed when the item's deepest descendant stays within the limit. Unindenting is always allowed, and menus that are already deeper than a newly configured limit remain editable: their items can be reordered and moved up, but never deeper.

#Translatable Menus

Built-in multilingual support with no extra packages required. Translatable fields are stored as JSON with locale tabs in the form UI.

#Setup

1. Enable translatable with your locales:

FilamentMenuBuilderPlugin::make()
    ->translatable(['en', 'nl', 'vi'])

2. Publish and run the migration to convert columns from string to json:

php artisan vendor:publish --tag="filament-menu-builder-translatable-migrations"
php artisan migrate

Existing string data is wrapped in the default locale (en). Edit $defaultLocale in the published migration to change this.

#Configuring Translatable Fields

Only MenuItem.title is translatable by default:

FilamentMenuBuilderPlugin::make()
    ->translatable(['en', 'nl', 'vi'])
    ->translatableMenuItemFields(['title'])  // default
    ->translatableMenuFields(['name'])       // opt-in: make Menu name translatable too

#Rendering Translated Titles

Use resolveLocale() in Blade to display titles in the current locale:

@foreach($menu->menuItems as $item)
    <a href="{{ $item->url }}">
        {{ $item->resolveLocale($item->title) }}
    </a>
@endforeach

resolveLocale() returns the translation for app()->getLocale(), falls back to the first available translation, or returns the raw string for non-translatable setups.

#Spatie Translatable Compatibility

The JSON format is compatible with Spatie Laravel Translatable. If you add HasTranslations to a custom model, the plugin detects it and defers to Spatie's mutators.

use Spatie\Translatable\HasTranslations;

class CustomMenuItem extends MenuItem
{
    use HasTranslations;

    public array $translatable = ['title'];
}

#Custom Models

Replace the default models with your own:

FilamentMenuBuilderPlugin::make()
    ->usingMenuModel(CustomMenu::class)
    ->usingMenuItemModel(CustomMenuItem::class)
    ->usingMenuLocationModel(CustomMenuLocation::class)

#Rendering Menus

Retrieve a menu by location. Results are cached and automatically busted on changes:

use Datlechin\FilamentMenuBuilder\Models\Menu;

$menu = Menu::location('header');

Render menu items:

@if($menu)
    <nav>
        <ul>
            @foreach($menu->menuItems as $item)
                <li class="{{ $item->classes }} {{ $item->isActive() ? 'active' : '' }}">
                    @if($item->url)
                        <a href="{{ $item->url }}" target="{{ $item->target }}" @if($item->rel) rel="{{ $item->rel }}" @endif>
                            {{ $item->resolveLocale($item->title) }}
                        </a>
                    @else
                        <span>{{ $item->resolveLocale($item->title) }}</span>
                    @endif

                    @if($item->children->isNotEmpty())
                        <ul>
                            @foreach($item->children as $child)
                                <li>
                                    <a href="{{ $child->url }}">{{ $child->resolveLocale($child->title) }}</a>
                                </li>
                            @endforeach
                        </ul>
                    @endif
                </li>
            @endforeach
        </ul>
    </nav>
@endif

#Active State Detection

Check if a menu item matches the current URL:

$item->isActive();                 // exact URL match
$item->isActiveOrHasActiveChild(); // matches self or any descendant

#MenuItem Properties

#Testing

composer test

#Changelog

See CHANGELOG for recent changes.

#License

MIT License. See LICENSE.md.