Filament Page With Sidebar Laravel Package

Getting Started

What it actually is. A layout package, not a plugin. It swaps Filament's default page chrome (header actions + horizontal sub-navigation) for a two-column layout: a persistent left sidebar listing every page of a resource — List, Create, Edit, View, plus any custom pages you register — and the page content on the right. There is no panel-provider registration step in the typical setup; you opt in per page class.

Match the package major to your Filament major — this is now the whole story. Release 3.0.0 is the Filament v4 release. It is a compatibility bump, not a feature release: the only functional change is PR #58 ("filament v4"); everything else in the changelog is Dependabot CI bumps and a README typo fix. So:

Pin explicitly rather than relying on composer require resolution:

composer require "aymanalhattami/filament-page-with-sidebar:^3.0"
composer show aymanalhattami/filament-page-with-sidebar
composer show filament/filament

Then publish the views (and config, if present in your version):

php artisan vendor:publish --tag="filament-page-with-sidebar-views"
php artisan vendor:publish --tag="filament-page-with-sidebar-config"

Where to look first. In this order:

1. The README's usage block on the 3.0.0 tag — it shows the exact trait name and the method signature for sidebar items. The API moved between Filament majors and there is no upgrade guide, so read the one that matches your installed version, not main.
2. The 3.0.0 diff against 2.6.0 (vendor/ or GitHub compare view) — it's small. Confirming "only Filament v4 compatibility changed" tells you whether this is a drop-in or a rework for your pages.
3. vendor/aymanalhattami/filament-page-with-sidebar/src/ — the trait and base page class read end to end in about ten minutes.
4. resources/views/ inside the package (and your published copy) — the layout, wire:navigate behaviour, and Tailwind classes live here.

First use case. Pick one resource that is already annoying: PostResource with index, create, edit, view, and a custom "Revisions" page. Convert it:

use AymanAlhattami\FilamentPageWithSidebar\...; // trait per the 3.0.0 README

class ListPosts extends ListRecords
{
    use HasPageWithSidebar;

    protected static string $view = 'filament-page-with-sidebar::page-with-sidebar';

    // sidebar items per README
}

Do the same on CreatePost, EditPost, and the custom page, then click through: verify the sidebar highlights the correct item on each page, that Edit links carry the current record id, and that the URLs match the resource's getPages() definitions. If that works, roll it out via a shared base class rather than copy-paste.

Expect roughly an hour for the first resource including reading the source, then ten minutes per additional resource.

Implementation Patterns

One base class, many pages. Don't sprinkle the trait across twenty page classes. Create App\Filament\Resources\Pages\SidebarListRecords, SidebarEditRecord, etc., each applying the trait and setting $view, then have resource pages extend those. This gives you a single place to fix the sidebar when the package updates — which matters more than usual here, since the last major release was purely a Filament-version adaptation.

Do the Filament v4 migration as a package migration, not a code migration. Going v3 → v4 means upgrading Filament and the package together. Since 3.0.0 introduces no new API surface, the practical sequence is: upgrade Filament first, get pages rendering, then bump the package and re-check the $view override and sidebar item signatures. Because your base classes concentrate the trait, this is a two-line change in composer.json plus a click-through — unless you've scattered the trait, in which case it's a hunt.

Drive the sidebar from getPages(), not from hand-written arrays. The resource already declares its pages and their routes; the package reads that. Hand-maintaining a parallel array of sidebar links is the number one source of drift — a renamed slug or a moved custom page silently breaks the sidebar, and after a Filament major that drift is invisible until someone clicks.

Record-scoped items need the record. On EditPost the sidebar's "View" and "Revisions" links need $this->getRecord(). On CreatePost there is no record, so record-scoped items either can't resolve or must be hidden. Make this explicit per page class — a Create page should show a reduced sidebar (List, and maybe nothing else).

Authorization is your job. A sidebar item is a UI affordance, not a gate. Filter items by auth()->user()->can(...) or by the resource's policy before returning them, otherwise a user with viewAny but not create sees a Create link and hits a 403. Test this with a low-privilege role — it's the most common production surprise with any sidebar package.

Settings-hub pattern (arguably the best use). The strongest case isn't resources at all: a set of standalone Filament pages (General, Mail, Payments, Notifications, API keys) under one /settings route with a fixed sidebar. Filament's top-level navigation gets cluttered fast here; a sidebar hub reads better and scales to fifteen pages. Use the same pages list for every settings page, and mark the active one.

Remove the duplicate navigation. If you leave Filament's getSubNavigation() in place you get two navigations pointing at the same destinations. Either drop the sub-navigation on these pages or don't adopt the sidebar for that resource. Pick one per resource and be consistent across the panel.

Header actions don't disappear for free. Once the header is replaced, "Create" lives in the sidebar. Keep delete/EditAction-style header actions (they still render above the content in most setups) but move navigation-shaped actions into the sidebar. Table bulk actions and row actions are unaffected.

Counts and badges. Status counts in a sidebar ("Drafts 42") are tempting and are a per-request query. Cache them (Cache::remember(..., 60)) or compute them once in a mount()-adjacent method, not inside the render path.

Testing. Cover the sidebar with Livewire assertions per role: assert the Edit link exists for an owner and not for a viewer. That's cheaper than discovering it in staging, and it catches breakage on Filament upgrades — which, given 3.0.0 exists solely to track Filament v4, is precisely where this package will bite you again at v5.

Gotchas and Tips

3.0.0 is a major bump with no upgrade guide. Treat it as breaking until proven otherwise. Read PR #58's diff against your current version before bumping in a production branch, and note that Filament v4 itself is the larger migration — the package change is the easy half. Pin with a caret plus a lockfile, and treat every composer update touching Filament as requiring a manual click-through of one resource's sidebar.

Expect nothing new. No features, no deprecations, no API additions in 3.0.0. If you were waiting on a fix or a capability, it isn't here. That also means the assessment of the package's shape is unchanged: 4–10 flat destinations, no nested groups, no search.

Plan for the bus factor. 273 stars, one maintainer, no dependents reported on Packagist. 3.0.0 arriving months after Filament v4 — and consisting solely of that compatibility work — illustrates the pattern: you are the support team, and you wait for one person's free time. Mitigation is cheap: fork into a private VCS repo, or copy the trait and Blade view into your codebase and own ~200 lines. The package is small enough that vendoring is legitimate, and it makes Filament v5 trivially survivable and removes the major-version coupling entirely.

Diff published views after upgrades. Published views override the package's, so a fix in a new release won't reach you — and if you published under 2.x and bump to 3.0.0, you're running v3 Blade against v4 Filament. Keep a note of which files you've published and re-diff after each update; the layout class names change when Filament's Tailwind classes change, and stale classes are the usual cause of "the sidebar looks broken after upgrading."

Confirm $view is actually applied. The classic failure is a page that renders normally with no sidebar because protected static string $view wasn't overridden, or was overridden on a parent that a child re-declared. This is the most likely symptom of a half-finished v4 upgrade. php artisan view:clear and a dd(static::$view) in mount() settle it in seconds.

Custom theme builds. If you use a custom Filament theme rather than the default, the package's Blade may reference Tailwind classes your build doesn't include. Either add the package's views to your theme's content paths in tailwind.config.js or publish and rewrite the markup with your own classes. Re-check this after v4 — Filament's utility set moved.

Livewire navigation. Filament v3/v4 pages use wire:navigate for SPA-style transitions. If the published sidebar markup uses plain <a href> (or your custom items do), you get full page reloads — noticeably slower and it loses scroll state. Add wire:navigate to your custom items.

Multi-panel caveat. Views and traits are global; sidebar item sets are per page class. If you run an admin and a customer panel off one codebase, define panel-specific base page classes rather than branching inside getSidebarItems() on Filament::getCurrentPanel() — the latter gets unreadable fast — and expect to migrate both at once when the next Filament major lands.

Don't force it where it doesn't fit. If you need collapsible groups, nested sections, or twenty-plus destinations with search, a sidebar package built around resource pages will fight you. Filament's built-in sub-navigation or a small custom Blade layout is the better answer there. This package's sweet spot is 4–10 flat destinations, which covers most resource pages and almost every settings hub.