Filament Header Select Laravel Package

Getting Started

This is a small, single-purpose Filament panel plugin: it swaps the default topbar navigation for a rounded, color-system-aware header select. With 24 stars and zero dependents, treat it as a convenience UI layer rather than infrastructure — worth a spike, not a critical dependency.

Minimal steps

1. Confirm Filament compatibility. The last release is 2025-09-04, which puts it in the Filament v4 / Laravel 11–12 era. Check composer.json for the exact filament/filament constraint before installing; don't assume it works on v3.
2. Install into the app (not a package):

   composer require solution-forest/filament-header-select
   

3. Register the plugin on the panel you want it on, in app/Providers/Filament/AdminPanelProvider.php:

   ->plugins([
       \SolutionForest\FilamentHeaderSelect\HeaderSelectPlugin::make(),
   ])
   

   Verify the actual plugin class name from src/ or the README — the namespace casing is the usual first trip-up.
4. Publish assets if the package ships CSS/JS:

   php artisan vendor:publish --tag="filament-header-select-assets"
   php artisan filament:assets
   

5. Clear caches and load the panel: php artisan optimize:clear.

Where to look first

• README.md for the plugin registration snippet and any config keys.
• src/*Plugin.php — the make() signature tells you what is configurable (colors, rounding, navigation source).
• resources/views/ — the Blade template is where the header actually renders; this is the file you'll publish if you need to restyle.
• config/filament-header-select.php (if present) — the color/rounding contract lives here.

First use case

A single admin panel where you want the topbar to look less like stock Filament and more like a product shell: one rounded, colored select in the header instead of the default nav strip. Wire it up on one panel, screenshot it, and decide whether the styling matches your brand before rolling it to tenant or multi-panel setups.

Implementation Patterns

Per-panel opt-in, not global. Register the plugin only on panels where the header treatment is wanted. In multi-panel apps (e.g. AdminPanelProvider + AppPanelProvider), leaving the plugin off the customer-facing panel avoids fighting Filament's own topbar there.

Lean on the color system, don't hardcode hex. The package's stated value is a "proper color system" — pass Filament palette keys (primary, gray, success, danger) or the panel's configured colors rather than raw values. This keeps the header consistent when you switch ->colors([...]) or run multiple panels with different brand colors.

Pair with ->topNavigation() intentionally. If the panel already enables top navigation, decide which component owns the header. The common pattern is: top navigation for cross-resource links, this plugin for the primary context switcher (tenant, team, workspace). Don't stack two nav bars; suppress one.

Handle custom themes with Tailwind content globs. If you use ->viteTheme('resources/css/filament/admin/theme.css'), add the package's views to your Tailwind content array so its classes survive purging:

content: [
  './vendor/solution-forest/filament-header-select/resources/views/**/*.blade.php',
  // ...existing Filament globs
]

Skipping this is the single most likely reason the header renders unstyled.

Publish the view before you fork behavior. For anything beyond color/rounding tweaks — adding a badge, changing the label format, injecting a Livewire action — publish the Blade view and override it in resources/views/vendor/filament-header-select/. Keeps you upgradable.

Test the panel boots. A cheap smoke test that hits the panel route as an authenticated user catches 90% of plugin integration failures (missing asset, bad namespace, config cache staleness) before deploy.

Gotchas and Tips

Version alignment is the real risk. 24 stars and zero dependents means almost no one has stress-tested this against Filament minor bumps. Pin the version in composer.json and re-verify the header after every filament/filament upgrade. A broken topbar is a whole-panel outage, not a cosmetic bug.

Assets and config caching. After publishing or changing config: php artisan filament:assets && php artisan optimize:clear. On production with config:cache, a stale published config silently ignores your changes — a classic "I edited it and nothing happened."

Dark mode and contrast. Rounded colored headers are where dark-mode contrast bugs live. Check the select's text/background pair in both modes, and check the focus ring — custom header components frequently lose Filament's focus-visible styling.

Tailwind purging in vendor views. As above: if the header renders as unstyled text, it's almost always the missing content glob, not a broken install. Confirm by checking whether the element has classes in the DOM but no matching CSS in the built bundle.

Low-adoption due diligence. Read the source before adopting — it's small, so this is minutes of work. Specifically check: does it override any core Filament view or just add one? Does it register global CSS that could leak into other panels? Does it touch the renderHook system in a way that conflicts with other header plugins?

Extension points, in order of preference: plugin config → published config file → published Blade view → custom theme CSS → forking. If you find yourself needing a fourth level, the package is probably the wrong tool and a small custom renderHook in your own panel provider is cheaper to maintain.

Debugging checklist when the header doesn't appear: plugin registered on the correct panel provider → panel provider is actually the one serving the route → assets published and built → user has panel access → no other plugin is overriding the topbar render hook. php artisan about and a ray()/dump() in the plugin's register()/boot() will localize the failure in one pass.