Filament Navigation Enhanced Laravel Package

Getting Started

This package extends Filament's panel navigation, letting you manage sidebar items (and their children) as data rather than hardcoded in Panel::navigationItems(). The v1.0.4 patch is a low-risk upgrade — no composer.json constraint change, no breaking API — so start by bumping:

composer update agroezinger/filament-navigation-enhanced
php artisan filament:optimize-clear   # if you cache components/icons

Where to look first:

1. The registered plugin class (usually in app/Providers/Filament/*PanelProvider.php) — this is where configuration, caching, and any item-resolution callbacks live.
2. The navigation resource/page the plugin registers — that's your day-to-day editing surface for items, labels, ordering, and parent/child structure.
3. The published config (config/filament-navigation-enhanced.php, if present) — check caching and visibility defaults before you build anything on top.

First use case to validate the upgrade: open a panel with a group that has children, mark one child ->visible(false) (or ->hidden()), and confirm it disappears from the sidebar and is not reachable. That's precisely the bug fixed in v1.0.4 — previously the child still rendered and clicking it landed on a page that returned 403. If your app relies on rendering-but-forbidding (some teams do this deliberately for upsell/teaser links), audit for that pattern now; it will no longer work.

Also spot-check labels on Filament 5.10.2+: labels are now passed via a dedicated label prop instead of only the slot. The component falls back to the slot when the prop is absent, so mixed Filament versions across apps are fine — but if you've published/overridden the sidebar item view, re-test it. A custom view that reads only $slot will still work; one that reads only a label variable may now behave differently.

Implementation Patterns

Data-driven items, code-driven policy. Keep the item tree in the database (via the resource) but keep authorization in policies/Gates. Let the plugin's visibility flags mirror your authorization rules rather than replace them — v1.0.4 makes the sidebar honest about visibility, so the two should agree. A clean pattern:

// in the item definition / resource form
->visible(fn () => auth()->user()?->can('viewAny', Post::class))

and the identical check in the PostPolicy. Divergence is now visible to users as missing links rather than dead links — better UX, but it makes stale policies easier to miss.

Group + child structure. Use parents for sections (e.g. "Content", "Settings") and children for the actual resources. Because hidden children are now filtered out of the rendered tree, a group whose children are all hidden will look empty — decide whether to hide the parent too (->visible(fn () => ...) on the parent, computed from the same source of truth) or accept an empty group. Prefer computing parent visibility with a shared helper so the two can't drift.

Multi-panel reuse. If you run an admin panel and a lighter "staff" panel, define the item set once and vary visibility per panel via the current panel ID. This is the main reason to use a navigation package over hardcoded navigationItems(), and it's the pattern most teams end up needing within a month.

Caching. Navigation trees are read on every authenticated page render. If the config exposes caching, enable it in production and flush on item save (model observers on the navigation item model are the natural hook). During development keep it off — stale sidebars after editing items are the #1 source of "the package is broken" reports.

Version pinning across a team. Since the label fix is backward-compatible across Filament 5.x, you can upgrade the package and Filament independently. Pin filament/filament to a minor you've tested, but you don't need to coordinate the two upgrades — useful when one team owns the panel and another owns the Filament bump.

Gotchas and Tips

• The v1.0.4 behavior change is the one to watch. ->visible(false) / ->hidden() children are now excluded from the rendered tree entirely. Anything that depended on them rendering — teaser links, "upgrade to see this" placeholder items, screenshot-accurate docs, E2E tests asserting link counts — needs revisiting. Grep your codebase for ->hidden() and ->visible( and confirm the intent is "don't show" not "show but block."
• 403s after clicking a nav item were the symptom of the pre-1.0.4 bug. If you worked around it by removing visibility flags and relying only on policies, you can now restore the flags — but keep the policy checks. Visibility is not authorization.
• Label prop vs. slot on Filament 5.10.2+. If you override the sidebar item Blade view, read the label prop first and fall back to $slot. The package does this internally; your override won't inherit that fallback automatically. Symptom of getting it wrong: blank sidebar labels on newer Filament, fine on older.
• Don't pin Filament 5.10.2+ as a hard requirement. The release explicitly avoided a constraint bump. If you see a PR adding "filament/filament": "^5.10.2", question it — it needlessly narrows compatibility.
• Debugging missing items: check in this order — (1) item is_visible/hidden state in the DB, (2) the visibility closure's return value for the current user, (3) navigation cache, (4) parent item hidden. Because children are now filtered, a hidden parent removing a whole subtree is easy to misread as "children deleted."
• Debugging wrong labels: check whether the label is set on the item record or only in a translation file, then confirm which Filament version is actually installed (composer show filament/filament) — the rendering path now differs.
• Extension point worth knowing: the item model and its visibility logic are the safest place to hook custom rules (e.g. feature-flag rollouts, tenant scoping). Prefer a small subclass or observer over editing published views — view overrides are what broke with the label change, and they'll break again.
• Upgrade check for this release: run your panel test suite (or a quick manual pass) against both a hidden child and a visible child group, and confirm labels render if you're on Filament ≥ 5.10.2. That covers both fixes in v1.0.4.