Filament Inner Nav Laravel Package

Getting Started

Install and register

composer require rawilk/filament-inner-nav
php artisan vendor:publish --tag="filament-inner-nav:config"   # if config is offered
php artisan vendor:publish --tag="filament-inner-nav:views"    # only if you need to override markup
php artisan filament:assets                                    # required in v1.1.1 — CSS is no longer global

Look here first

1. README.md — the component/trait name and the exact prop signature move between minor versions; copy the snippet rather than guessing.
2. resources/views/ — the published markup is the fastest way to understand how the nav is structured and which Tailwind/Filament classes drive the sticky layout.
3. config/filament-inner-nav.php — defaults for sticky offset, active-item behaviour, and (from v1.1.1) CSS/asset registration.
4. src/ — check whether the package exposes a Filament render hook, a panel plugin, or a plain Blade component; that determines where you mount it.

First use case: a long EditSettings / EditProfile custom page with 4–8 logical sections. Drop the inner nav into a two-column layout next to the form so users can jump between "General", "Notifications", "Billing", etc., with the active section highlighting as they scroll.

Implementation Patterns

Mount inside a custom page, not the panel

The nav is page-scoped by design. Give your custom Filament page a Blade view and render the package component there, inside the page's grid wrapper:

<x-filament-panels::page>
    <div class="grid gap-6 lg:grid-cols-[16rem_minmax(0,1fr)]">
        <aside class="hidden lg:block">
            <x-filament-inner-nav::inner-nav :items="$this->getInnerNavItems()" />
        </aside>

        <div class="space-y-8">
            <section id="general" class="scroll-mt-24">…</section>
            <section id="notifications" class="scroll-mt-24">…</section>
        </div>
    </div>
</x-filament-panels::page>

Define items once, in PHP

Keep anchor IDs and labels in a single method or config array so the nav and the section markup can never drift:

public function getInnerNavItems(): array
{
    return [
        ['id' => 'general',       'label' => __('General')],
        ['id' => 'notifications', 'label' => __('Notifications')],
        ['id' => 'billing',       'label' => __('Billing')],
    ];
}

If the package supports auto-discovery of headings, prefer it for content-style pages and manual items for form pages — auto-discovery of <h2>s breaks the moment a section heading is hidden behind a @if.

Sticky behaviour + anchor offset

Two independent knobs, both needed:

• The nav container gets sticky top-<topbar height> in your layout (Tailwind, not the package).
• Each target section gets scroll-mt-24 (or whatever your topbar is) — otherwise the anchored section lands under the fixed topbar and looks broken.

Livewire / SPA navigation

The scroll-spy listener and any intersection observers must be re-initialised after wire:navigate and after Livewire morphs. Wrap the nav in wire:ignore when its items are static, and re-init on livewire:navigated:

document.addEventListener('livewire:navigated', () => initInnerNav());

Custom Filament theme

If the panel uses ->viteTheme(...), the on-demand asset loader from v1.1.1 may not be the only CSS path — add the package's stylesheet to your theme's resources/css/filament/admin/theme.css so the nav styles survive your own build:

@import '../../../../vendor/rawilk/filament-inner-nav/resources/dist/filament-inner-nav.css';

Run npm run build afterwards. This is also the safest route if you publish and rewrite the views.

Gotchas and Tips

• v1.1.1 "Load CSS on demand" is the one change that can bite on upgrade. After composer update, run php artisan filament:assets and php artisan view:clear. If the nav renders unstyled, that's almost always a missing asset publish or a cached asset manifest, not a broken install. Check the browser network tab for the package CSS file first.
• Custom compiled themes bypass on-demand loading. If you have a Vite-built panel theme, import the CSS manually (see above) — the automatic registration path is designed for the default (non-compiled) panel setup.
• Duplicate or unstable IDs. Anchors must be unique across the whole page and stable across Livewire re-renders. IDs generated from a model key that changes (e.g. a newly created form row) will silently break deep links and scroll-spy highlight.
• Sticky + overflow-hidden is fatal. Any ancestor with overflow: hidden / overflow-x-auto kills position: sticky with no error. Filament's table wrappers and some widget containers do this — check the ancestor chain before rewriting your CSS.
• Scroll-spy thrash on long pages. Intersection observers and scroll listeners on 20+ sections can jank on low-end devices; throttle, or limit the nav to the top-level sections only.
• Mobile. Don't render the sticky sidebar below lg unless you add a fallback (a <select> jump menu or an accordion). A sticky sidebar on a 375px viewport eats the form.
• Publish, don't patch. Editing files under vendor/ will be wiped on the next composer update; publish the views into resources/views/vendor/filament-inner-nav/ instead.
• Debugging order: (1) does the component render at all (inspect DOM for its wrapper class), (2) is the CSS file in the network tab, (3) is the sticky ancestor clean, (4) is scroll-mt set on targets.
• The dependency bumps in v1.1.1 (tailwindcss 3.3.3 → 3.3.5, git-auto-commit-action 4 → 5) are build/CI-only and require nothing from consuming applications.