Weave Code
Filament Collapsible Subnav Laravel Package
emuniq/filament-collapsible-subnav
A Filament v3, v4, and v5 plugin that adds a collapsible toggle to sub-navigation sidebars on resource pages. It auto-registers to all panels with zero configuration and works with both top and sidebar navigation layouts.
Filament Collapsible Sub-Navigation adds a collapsible toggle to the sub-navigation sidebar on individual resource pages in Filament v3, v4, and v5 panels. Ideal for resources with many tabs or sections using ->subNavigationPosition(SubNavigationPosition::Start), it works with both top navigation and sidebar navigation layouts while leaving the main panel navigation untouched.
Install with Composer and it auto-registers to all panels with zero configuration and no flash.
- Zero-config setup with auto-registration
- Targets sub-navigation sidebars only
- Supports Filament v3, v4 & v5
- Optional theme integration for fewer HTTP requests
- Works with top and sidebar panel layouts
Frequently asked questions about Filament Collapsible Subnav
- How do I install emuniq/filament-collapsible-subnav in a Laravel app?
- Run composer require emuniq/filament-collapsible-subnav in your Laravel project. The service provider is auto-discovered and the plugin auto-registers to all Filament panels, so no manual registration step is required. Open a resource page that uses a sub-navigation sidebar and the toggle appears immediately, with no flash of unstyled navigation. No migrations, published config files or environment variables are involved.
- Does this plugin support Filament v3, v4 and v5?
- Yes. A single version constraint covers Filament v3, v4 and v5, and the package requires PHP 8.1 or higher with Laravel 10, 11, 12 or 13. If you want predictable behaviour, pin an exact version such as 1.6.0 rather than ^1.6, and record the Filament and PHP versions you verified it against. The ^1.0 release line already supported v3 through v5.
- Does the collapsible toggle affect the main sidebar navigation?
- No. The plugin only targets the secondary sub-navigation rail that appears inside individual resource pages and never touches the main panel navigation. It works whether your panel uses top navigation or a classic sidebar layout. The sub-navigation itself only exists when a resource sets ->subNavigationPosition(SubNavigationPosition::Start).
- Do I need to register the plugin or publish a config file?
- The plugin auto-registers to every panel out of the box, so there is nothing to configure and no config file to publish. If you prefer explicit control you can still add CollapsibleSubnavPlugin::make() to your panel's plugin() array in the panel provider. There are no migrations, asset publishing steps or environment variables to manage.
- Which Filament resource pages benefit from a collapsible sub-navigation sidebar?
- It is aimed at resource pages whose sub-navigation has grown to many tabs or sections, where the secondary rail eats horizontal space and makes long tab lists hard to scan. Enable ->subNavigationPosition(SubNavigationPosition::Start) on the resource and the plugin adds a toggle to collapse that rail. Pages with only two or three tabs gain little, so apply it selectively to high-density resources rather than globally.
- Does the plugin work when the Filament panel uses SPA mode?
- Yes, it works with panels that enable ->spa(). The plugin re-syncs its state on the livewire:navigated event, which keeps the toggle and the collapsed class correct after client-side navigation. Without that hook the sub-navigation would revert to its expanded state after every SPA transition. This is the one behaviour that is genuinely non-trivial to reimplement yourself.
- Is the collapsed state remembered per user or per browser?
- The collapsed state is stored in a cookie, so it is remembered per browser and per device rather than per user account. Two people sharing a machine share the state, and the same person on a phone and a laptop will have independent states. If you need per-user persistence you would have to layer your own preference storage on top of the plugin.
- How do I bundle the plugin CSS into my Filament theme?
- Run php artisan collapsible-subnav:install and then npm run build to bundle the plugin CSS with your existing Filament theme. This removes one HTTP request and is entirely optional, because the plugin works correctly without it thanks to runtime CSS injection. It is a reasonable optimization to skip on a first pass and add once the feature is confirmed.
- Is the plugin safe to use with a strict Content Security Policy?
- The plugin injects a small inline script into the panel head so the collapsed class is applied before render and users see no flash, and no nonce or hash support is documented. With a strict Content Security Policy that blocks inline scripts you will need to add a nonce or hash yourself, or the anti-flash behaviour and possibly the toggle will fail. Test against a panel that mirrors your production CSP headers before rolling out, and check whether any HTML minifier strips data-cfasync attributes.
- Will a Filament upgrade break the plugin, and how do I roll back?
- The main risk is coupling to Filament's internal CSS class names: v1.6.0 of the plugin exists largely because Filament v4 renamed .fi-sidebar-item-button to .fi-sidebar-item-btn, which silently broke tooltips, with badge hiding and collapsed-button padding patched in the same release. Pin an exact plugin version and re-verify the sub-navigation after each Filament upgrade rather than relying on automated tests. Rollback is cheap: composer remove emuniq/filament-collapsible-subnav plus deleting one line from the panel provider, so the cost of trying it is bounded.
Weaver
How can I help you explore Laravel packages today?