Search by

solutionforest / filament-drilldown-nav

solutionforest

Drill-down sidebar navigation for Filament v5 panels: one level at a time, a menu per record, any depth.

v0.6.2 2026-11-17 08:02 UTC

This package is auto-updated.

Last update: 2026-11-17 08:04:05 UTC


README

Filament Drilldown Nav: one sidebar, one level at a time, a menu for every record

Filament Drilldown Nav

Drill-down sidebar navigation for Filament v5 panels: one level at a time, a menu for every record, any depth.

Latest release Tests Packagist version Total downloads PHPStan level 10 Filament v5 only PHP 8.3+ Laravel 13 Livewire 4 Octane: RoadRunner, Swoole, FrankenPHP MIT license Status: before 1.0

📚 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

Journey: main menu, projects table, one project, files sub menu

📂 A client's menu, real badges 🧱 Five levels deep 🔎 Search all levels 📌 Pinned pages
client menu task menu search pinned
🌙 Dark 📱 Mobile drawer 🇸🇦 Right to left ▫️ Collapsed
dark mobile rtl 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