README

Configure your Filament navigation via a simple PHP configuration file - no manual navigation building required!

Perfect for applications where navigation needs to be easily manageable, version-controlled, and consistent across environments.

✨ Features

• ✅ Simple Configuration - Define navigation in a clean PHP config file
• ✅ Full Control - Groups, direct links, and visual separators
• ✅ 24 Separator Styles - From classic lines to hearts and stars
• ✅ Order Preservation - Array order = display order
• ✅ External Links - Support for external URLs with target="_blank"
• ✅ Icon Support - Full Heroicon support for groups and items
• ✅ No Hover on Separators - Automatically disables hover effects
• ✅ Filament 4 Compatible - Built specifically for Filament 4.x

📦 Installation

Install via composer:

composer require shuxx/filament-navigation

Publish the configuration file:

php artisan vendor:publish --tag="filament-navigation-config"

This creates config/filament-navigation.php.

🚀 Quick Start

1. Register the plugin

In app/Providers/Filament/AdminPanelProvider.php:

use Shuxx\FilamentNavigation\FilamentNavigationPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentNavigationPlugin::make());
}

2. Configure your navigation

Edit config/filament-navigation.php:

return [
    'items' => [
        // Dashboard
        [
            'type' => 'link',
            'label' => 'Dashboard',
            'url' => '/admin',
            'icon' => 'heroicon-o-home',
        ],

        // Separator
        ['type' => 'separator', 'style' => 'default'],

        // Users Group
        [
            'type' => 'group',
            'label' => 'Users',
            'icon' => 'heroicon-o-user-group',
            'collapsible' => true,
            'items' => [
                ['type' => 'link', 'label' => 'All Users', 'url' => '/admin/users'],
                ['type' => 'link', 'label' => 'Roles', 'url' => '/admin/roles'],
            ],
        ],

        ['type' => 'separator', 'style' => 'dots'],

        // External link
        [
            'type' => 'link',
            'label' => 'Documentation',
            'url' => 'https://filamentphp.com/docs',
            'icon' => 'heroicon-o-book-open',
            'external' => true,
        ],
    ],
];

That's it! Your navigation is now configured. 🎉

📖 Documentation

Available Types

Group

Creates a collapsible navigation group:

[
    'type' => 'group',
    'label' => 'Settings',
    'icon' => 'heroicon-o-cog-6-tooth',
    'collapsible' => true,  // optional, default: true
    'items' => [
        // ... sub-items
    ],
]

Link

Creates a navigation link:

[
    'type' => 'link',
    'label' => 'Dashboard',
    'url' => '/admin/dashboard',
    'icon' => 'heroicon-o-home',  // optional
    'external' => false,  // optional, opens in new tab if true
]

Separator

Creates a visual separator:

[
    'type' => 'separator',
    'style' => 'default',  // optional, see styles below
]

🎨 Separator Styles (24 options)

Classic Lines

• default → ───────────
• long → ────────────────
• double → ═══════════
• thick → ━━━━━━━━━━━
• dash → - - - - - - - -
• underscore → ___________

Dots and Circles

• dots → • • • • • • • •
• circle → ○ ○ ○ ○ ○ ○
• circle-filled → ● ● ● ● ● ●
• ellipsis → ⋯ ⋯ ⋯ ⋯ ⋯

Geometric Shapes

• square → ▪ ▪ ▪ ▪ ▪ ▪
• diamond → ◆ ◆ ◆ ◆ ◆
• triangle → ▸ ▸ ▸ ▸ ▸ ▸
• arrow → → → → → →
• chevron → › › › › › ›

Special Symbols

• stars → ★ ★ ★ ★ ★
• hearts → ♥ ♥ ♥ ♥ ♥
• plus → + + + + + + +
• cross → ✕ ✕ ✕ ✕ ✕

Waves and Curves

• wave → ～～～～～～～
• wavy → 〰〰〰〰〰
• zigzag → ﹏﹏﹏﹏﹏

Spaces

• space → (large empty space)
• blank → · (minimal visible space)

Plugin Options

Disable Separator Hover

By default, separators have hover effects disabled. You can enable them:

FilamentNavigationPlugin::make()
    ->disableSeparatorHover(false)

⚠️ Important Notes

Filament 4 Icon Limitation

In Filament 4, you cannot have icons on both the group AND its items. Choose one:

Option 1 - Icons on groups (recommended):

[
    'type' => 'group',
    'icon' => 'heroicon-o-user-group',  // ✅ Icon here
    'items' => [
        ['label' => 'Users', 'url' => '...'],  // ❌ No icons
    ],
]

Option 2 - Icons on items:

[
    'type' => 'group',
    // ❌ No icon on group
    'items' => [
        ['label' => 'Users', 'icon' => 'heroicon-o-users'],  // ✅ Icons here
    ],
]

Navigation Order

The order of items in your config array is the display order. The plugin transforms everything into navigation groups internally to maintain order control (a Filament 4 requirement).

🧪 Testing

composer test

📝 Changelog

Please see CHANGELOG for recent changes.

📚 Documentation

• Installation Guide - Get started in minutes
• Usage Examples - Real-world navigation configs (Blog, E-commerce, SaaS, CRM, etc.)
• Separator Styles - All 24 available styles
• API Reference - Complete configuration options
• Changelog - Version history and updates

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING for details on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Development guidelines

💬 Support

Need help or have questions?

• 📖 Documentation - Check EXAMPLES.md for common use cases
• 🐛 Issues - Report bugs or request features
• 💡 Discussions - Ask questions or share ideas
• 📧 Email - Contact the author at github.com/shuxx

🔒 Security

If you discover any security-related issues, please email the author directly instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

💝 Credits

• Author: Shuxx
• Contributors: All Contributors
• Inspired by: Filament navigation system
• Built with: spatie/laravel-package-tools

📄 License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ for the Filament community

⭐ Star this repo if you find it helpful!