Filament Page Header Laravel Package

Getting Started

Start by confirming the Filament major version this package targets — with a small package like this (13 stars, single maintainer), the README is often thinner than the code, so treat composer.json requirements as the source of truth.

1. Install

   composer require mortalkiller/filament-page-header
   

2. Publish assets/config (if the package ships them)

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

   If the tag doesn't exist, check src/ for a ServiceProvider with publishes() calls before assuming there's nothing to configure.

3. Register the plugin in your panel provider if it implements Filament\Contracts\Plugin:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(\Mortalkiller\FilamentPageHeader\FilamentPageHeaderPlugin::make());
   }
   

   If it's trait-based instead, skip this and use the trait on the pages you want to customize.

4. First use case — the fastest win is almost always overriding the default heading/subheading on a Resource page. Apply the trait to a ListRecords/EditRecord/CreateRecord page (or the Resource itself, depending on how the package hooks in) and return your custom header from the relevant method. Run php artisan filament:optimize-clear and reload the page.

Where to look first if the README is sparse: src/ for the main trait/plugin class, then resources/views/ for the Blade template the header renders. The template tells you faster than any docs what slots, actions, and variables are available.

Implementation Patterns

Per-page header customization. The typical usage is a trait you drop on a Filament page class and then implement one or two methods — something like getHeaderHeading(), getHeaderSubheading(), or a single pageHeader() array/object. This keeps the customization local to the page instead of forking Filament's base views.

Dynamic headers from record context. On EditRecord and ViewRecord, pull from $this->getRecord() inside the header method so the title reflects the current model. Guard against null during the create flow if you share the trait across both pages.

Header actions and slots. If the package exposes a fluent API (.heading(), .subheading(), .actions([...]), .badge()), chain it in mount() or a getHeader() builder rather than rendering raw HTML. Prefer Filament Action objects over custom Blade buttons so modals, authorization, and confirmation dialogs keep working.

Panel-wide defaults. When several resources share a header style, define the default in the panel provider (or a base page class) and only override per-page. This is the pattern that scales — copy-pasting the trait into twenty pages is a maintenance trap.

Integration with widgets and stats. If your header is meant to sit above a stats overview, render it inside the page's getHeaderWidgets()/getFooterWidgets() region rather than injecting it into a resource view. That way it respects Filament's column layout and doesn't break on mobile breakpoints.

Authorization-aware headers. Wire any header actions through ->visible(fn () => auth()->user()->can(...)) rather than hiding with CSS — Filament actions already respect policies, so use the built-in gates.

Gotchas and Tips

• Method collisions. Filament's Page, Resource, and the HasRecords/InteractsWithHeader traits already define getHeading(), getSubheading(), getBreadcrumbs(). If this package shadows those names, override carefully and don't mix both APIs on the same page — you'll get confusing precedence bugs where one silently wins.

• Version drift is the biggest risk. Low stars + a 2026 release date means the package may not track Filament's breaking changes promptly. Pin it exactly in composer.json ("mortalkiller/filament-page-header": "1.2.*" not ^1.2) and add a smoke test that renders one resource page in CI. When Filament bumps majors, check the package's composer.json constraint before upgrading.

• View caching. Header changes often don't appear because of compiled Blade views. php artisan view:clear and php artisan filament:optimize-clear should be your first debugging step, not your last.

• Static assets vs. published views. If the header renders from a view inside the package's resources/views, publishing with --tag copies a snapshot — future package updates won't propagate. Only publish if you need to modify it, and document that you've done so.

• Livewire reactivity. Header values derived from record state won't update on Livewire re-renders unless the method is called fresh on each render. Avoid caching the header in a property; compute it in the render path.

• Read the source. With 13 stars, there's likely no Stack Overflow coverage and few blog posts. Budget an hour to skim src/ end to end — the public API is small enough that the source is the documentation. Fork it into a packages/ path dependency if you need even a one-line fix, rather than waiting on upstream.

• Extension point to prefer: if the package exposes a ->view() or ->headerView() override, use it for structural changes and keep the data shape intact. Overriding internal methods couples you to the implementation and will break on the next release.