solutionforest / filament-drilldown-nav
Drill-down sidebar navigation for Filament v5 panels: one level at a time, a menu per record, any depth.
Package info
github.com/solutionforest/filament-drilldown-nav
pkg:composer/solutionforest/filament-drilldown-nav
Requires
- php: ^8.3
- filament/filament: ^5.7
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Filament Drilldown Nav
Drill-down sidebar navigation for Filament v5 panels: one level at a time, a menu for every record, any depth.
📚 Documentation · 🚀 Usage guide · 🧩 API reference · ✅ Support matrix · 🎬 Demo · 📝 Changelog
✨ Features
| Feature | ||
|---|---|---|
| 🧭 | Drill-down levels | Click an item and the sidebar shows its menu, with a Back link and the section title. Any depth. |
| 🗂️ | A menu per record | Click a project, client or order and get that record's menu: ->record(), or built automatically from the resource's pages with ->recordPages(). Nested resources work. |
| ➕ | Expand in place | ->inline() sections with guide lines, nesting, an accordion mode, and an open/closed state that is rendered on the server (no flash). |
| 🔌 | Reuses Filament's navigation | NavItem::fromFilamentNavigation() imports your existing groups, parent items, badges, sorting and access checks. Clusters keep working. |
| 🔎 | Search | Filters the menu as you type, can search all levels (even unopened ones), and focuses with the / key. |
| 📌 | Recent and pinned pages | In the browser, or stored in the database per user, panel and tenant. |
| 🔢 | Live badges | pollBadges('30s') and the refresh-sidebar event keep counts such as "Unpaid 3" fresh. |
| 🪝 | Render hooks | Six Filament render hooks around the menu: add content without publishing views. |
| 📱 | Responsive | Collapsed icon rail, mobile drawer, dark mode. |
| 🌍 | 11 languages, right to left | English, 简体中文, 繁體中文 (TW, HK), 日本語, 한국어, Español, العربية, עברית, فارسی, اردو. |
| ⚡ | Octane-safe | Per-request state. Verified on real RoadRunner, Swoole and FrankenPHP workers, including under parallel load. |
| 🏢 | Multi-panel, tenancy, domains | Each panel has its own tree; URLs come from Filament, so tenants and domains just work. |
| ♿ | Accessible | aria-current, aria-expanded, focus moves to the new level, reduced-motion support. |
| 🛡️ | No view overrides | Nothing to re-publish after a Filament upgrade; works with a strict Content-Security-Policy. |
🧭 Why
Filament nests everything in the sidebar and shows a cluster's or page's sub-navigation as a second menu beside the content. That is fine for two levels. It gets awkward when a record has its own area with its own sub-menus (3 or 4 levels) and you want it all in one place.
| You want | Filament alone | This plugin |
|---|---|---|
| A menu for one record | build a sub-navigation per page | ->record(fn ($record) => [...]) |
| 3–4 levels in the left sidebar | groups + one parent level | any depth |
| One menu location | sidebar and sub-navigation | the sidebar |
Keep $navigationGroup, badges, canAccess() |
n/a | NavItem::fromFilamentNavigation() |
If two levels are enough, Filament's own groups, parent items and clusters are simpler: this plugin or Filament's navigation?
📸 Screenshots
| 📂 A client's menu, real badges | 🧱 Five levels deep | 🔎 Search all levels | 📌 Pinned pages |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
| 🌙 Dark | 📱 Mobile drawer | 🇸🇦 Right to left | ▫️ Collapsed |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
✅ Requirements
Filament v5 only. Filament v3 and v4 are not supported.
| Supported | |
|---|---|
| Filament | ^5.7: the oldest version (5.7.0) and the latest 5.x both run in CI |
| PHP | ^8.3 |
| Laravel / Livewire | 13 / 4 (the versions CI runs) |
| Octane | RoadRunner, Swoole, FrankenPHP |
The full, maintained table (and what each row means) is in docs/support.md. Run a patched Filament: versions below 5.8.3 have published security advisories, which Composer blocks by default.
📦 Installation
Install it with Composer from Packagist:
composer require solutionforest/filament-drilldown-nav
php artisan filament:assets # publishes the stylesheet (`php artisan filament:upgrade` does it too)
🚀 Quick start
use SolutionForest\DrilldownNav\DrilldownNavPlugin; use SolutionForest\DrilldownNav\Tree\NavItem; $panel->plugin(DrilldownNavPlugin::make()->items(fn () => [ NavItem::page(Dashboard::class), // label, icon, URL and access from the class NavItem::resource(ProjectResource::class) // the list is a normal Filament table ->recordPages(), // the menu INSIDE one project, built from its pages ...NavItem::fromFilamentNavigation(), // everything else Filament would show ]));
Prefer to write a record's menu yourself, nest levels, add search, pins, badges or hooks? Everything is in the usage guide.
In the sidebar, the plugin's menu replaces Filament's own list: only items returned from
items()are shown there. Everywhere else Filament's navigation is untouched (->topNavigation()still shows the native menu in the top bar).
📚 Documentation
| Page | What is in it | |
|---|---|---|
| 🚀 | Usage guide | Pages, resources, nested levels, record menus, native navigation, visibility, badges |
| ➕ | Modern navigation | Expand in place, accordion, headings, the collapsed sidebar, accessibility |
| 🔎 | Large menus | Search, shortcuts, recent and pinned pages, long lists, live badges |
| 🪝 | Render hooks | Add your own content around the menu |
| 🏢 | Panels, workers, tenants, languages | Multi-panel, Octane, tenancy, translations, right-to-left |
| 🧩 | API reference | Every public method (generated from the code) |
| 🔒 | API stability | What is public, what may change, and what 1.0 needs |
| ✅ | Support matrix | Filament, PHP, Laravel, Livewire, Octane |
| 🔌 | Works with other plugins | Checked next to five popular plugins |
| 🧠 | How it works | The problem, the request flow, diagrams |
| ⚖️ | This plugin or Filament's navigation? | A decision guide |
| 🎬 | The demo app | A realistic client portal with roles and 3,000 rows |
| 🧪 | Testing and quality | What is tested and how to run it |
| ❓ | FAQ and troubleshooting | Empty menu, missing styles, record menus that do not appear |
| ⬆️ | Upgrading | Notes for each release |
| 🤖 | AGENTS.md · SKILLS.md | For people and AI agents changing this repository / adding the plugin to an app |
🧪 Quality
| 🔬 PHPStan level 10 | the strictest level, no ignores, no baseline |
| 🧪 Pest + feature tests | the package, and a demo app that renders the real panels (100+ tests) |
| 📉 Oldest and newest Filament | the whole suite runs on 5.7.0 and on the latest 5.x |
| ⚡ Real Octane servers | RoadRunner, Swoole and FrankenPHP, one worker and four workers under parallel requests |
| 📖 Docs are tested too | a test keeps composer.json, the support matrix, the README, CI and the generated API reference in step, and checks every link |
composer check # Pint + PHPStan 10 + Pest (cd demo && php artisan test) # feature tests against the real panels
🗺️ Status and limits
The plugin is feature-complete for 1.0, but the API is not frozen yet: see API stability. Things to know:
- In the sidebar only the items you list (or import with
fromFilamentNavigation()) are shown. - Levels come from the URL (plus
activeOn()/activeWhen()), so a record's pages should live under the record's URL. - Pinned pages stored in the browser are per browser; use
pinnable(database: true)to sync them across devices. - Hebrew, Persian and Urdu strings are machine-written and welcome a native-speaker review.
🤝 Contributing, security, license
- Contributing: CONTRIBUTING.md and the code of conduct.
- Security: please report vulnerabilities privately: SECURITY.md.
- Changelog: CHANGELOG.md.
- License: MIT. Made by Solution Forest.









