Navigation
- Getting started
- Grouping navigation items
- Registering custom navigation items
- Advanced navigation customization
- Customizing the user menu
Getting started
By default, Filament will register navigation items for each of your resources and custom pages. These classes contain static properties and methods that you can override, to configure that navigation item and its order:
protected static ?string $navigationIcon = 'heroicon-o-document-text'; protected static ?string $navigationLabel = 'Custom Navigation Label'; protected static ?int $navigationSort = 3; protected static function getNavigationBadge(): ?string{ return static::getModel()::count();}
The $navigationIcon
supports the name of any Blade component, and passes a set of formatting classes to it. By default, the Blade Heroicons package is installed, so you may use the name of any Heroicon out of the box. However, you may create your own custom icon components or install an alternative library if you wish.
Grouping navigation items
You may group navigation items by specifying a $navigationGroup
property on a resource and custom page:
protected static ?string $navigationGroup = 'Settings';
All items in the same navigation group will be displayed together under the same group label, "Settings" in this case. Ungrouped items will remain at the top of the sidebar.
Ordering navigation groups
If you wish to enforce a specific order for your navigation groups, you may call Filament::registerNavigationGroups()
from the boot()
method of any service provider.
use Filament\Facades\Filament;use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider{ public function boot(): void { Filament::serving(function () { Filament::registerNavigationGroups([ 'Shop', 'Blog', 'Settings', ]); }); }}
Registering custom navigation items
Alternatively, you may completely override the static getNavigationItems()
method on the class and register as many custom navigation items as you require:
use Filament\Navigation\NavigationItem; public static function getNavigationItems(): array{ return [ NavigationItem::make() ->group($group) ->icon($icon) ->isActiveWhen($closure) ->label($label) ->badge($badge) ->sort($sort) ->url($url), ];}
Disabling resource or page navigation items
To prevent resources or pages from showing up in navigation, you may use:
protected static bool $shouldRegisterNavigation = false;
Advanced navigation customization
The Filament::navigation()
method which can be called from the boot
method of a ServiceProvider
:
use Filament\Facades\Filament;use Filament\Navigation\NavigationBuilder; Filament::navigation(function (NavigationBuilder $builder): NavigationBuilder { return $builder;});
Once you add this callback function, Filament's default automatic navigation will be disabled and your sidebar will be empty. This is done on purpose, since this API is designed to give you complete control over the navigation.
If you want to register a new group, you can call the NavigationBuilder::group
method.
use Filament\Facades\Filament;use Filament\Navigation\NavigationBuilder; Filament::navigation(function (NavigationBuilder $builder): NavigationBuilder { return $builder->group('Settings', [ // An array of `NavigationItem` objects. ]);});
You provide the name of the group and an array of NavigationItem
objects to be rendered. If you've got a Resource
or Page
you'd like to register in this group, you can use the following syntax:
use Filament\Facades\Filament;use Filament\Navigation\NavigationBuilder; Filament::navigation(function (NavigationBuilder $builder): NavigationBuilder { return $builder->group('Content', [ ...PageResource::getNavigationItems(), ...CategoryResource::getNavigationItems(), ]);});
You can also register ungrouped items using the NavigationBuilder::item()
method:
use Filament\Facades\Filament;use Filament\Navigation\NavigationBuilder; Filament::navigation(function (NavigationBuilder $builder): NavigationBuilder { return $builder->item( NavigationItem::make() ->label('Dashboard') ->icon('heroicon-o-home') ->isActiveWhen(fn (): bool => request()->routeIs('filament.pages.dashboard')) ->url(route('filament.pages.dashboard')), );});
Customizing the user menu
The user menu is featured in the top right corner of the admin layout. It's fully customizable.
To register new items to the user menu, you should use a service provider:
use Filament\Facades\Filament;use Filament\Navigation\UserMenuItem; Filament::serving(function () { Filament::registerUserMenuItems([ UserMenuItem::make() ->label('Settings') ->url(route('filament.pages.settings')) ->icon('heroicon-s-cog'), // ... ]);});
Customizing the account link
To customize the user account link at the start of the user menu, register a new item with the account
array key:
use Filament\Facades\Filament;use Filament\Navigation\UserMenuItem; Filament::serving(function () { Filament::registerUserMenuItems([ 'account' => UserMenuItem::make()->url(route('filament.pages.account')), // ... ]);});
Customizing the logout link
To customize the user account link at the end of the user menu, register a new item with the logout
array key:
use Filament\Facades\Filament;use Filament\Navigation\UserMenuItem; Filament::serving(function () { Filament::registerUserMenuItems([ // ... 'logout' => UserMenuItem::make()->label('Log out'), ]);});
Still need help? Join our Discord community or open a GitHub discussion