v2.3.0

[mortalkiller]

Filament Page Header v2.3.0

Filament Page Header 2.3 adds native Filament navigation support to the page header, including configurable breadcrumbs, Page/Resource sub-navigation, and compact-mode navigation control.

Existing headers keep their current behavior by default. Navigation features are opt-in.

What's new

Native header navigation

Breadcrumbs can now be positioned outside the header, inside the header, or hidden:

use MortalKiller\FilamentPageHeader\Enums\BreadcrumbPosition;

Header::make()
    ->breadcrumbs(BreadcrumbPosition::Inside);

Available positions:

• BreadcrumbPosition::Outside — default behavior
• BreadcrumbPosition::Inside
• BreadcrumbPosition::Hidden

Native Filament Page/Resource sub-navigation can now be moved into the page header:

Header::make()
    ->subNavigation();

The package continues to use Filament's native navigation data, including:

• URLs
• authorization
• active state
• icons and badges
• SPA navigation
• record sub-navigation
• ManageRelatedRecords

Relation Manager content tabs remain in their normal page-content location.

Compact navigation control

Breadcrumbs and sub-navigation can participate in the typed compact configuration:

use MortalKiller\FilamentPageHeader\CompactHeader;
use MortalKiller\FilamentPageHeader\Enums\HeaderPart;

Header::make()
    ->subNavigation()
    ->compact()
    ->whenCompact(fn (CompactHeader $compact) => $compact
        ->show(
            HeaderPart::Breadcrumbs,
            HeaderPart::SubNavigation,
        ));

New compact parts:

HeaderPart::Breadcrumbs
HeaderPart::SubNavigation

Native navigation blocks support show(). Field-level only() selection is intentionally not supported for navigation.

Refined desktop sub-navigation

Desktop sub-navigation now integrates directly into the header instead of looking like a second nested container.

The active tab:

• follows the panel primary color
• uses a simple underline
• aligns with the lower edge of the header
• keeps consistent spacing in expanded and compact layouts

Mobile continues to use Filament's native sub-navigation dropdown.

Keyboard focus is preserved when navigation would otherwise collapse in compact mode.

New documentation site

The package now has a dedicated Astro + Starlight documentation site:

https://docs.pedromonteiro.dev/filament-page-header/

It includes:

• installation and compatibility guides
• complete configuration documentation
• generator guide
• migration guide
• API reference
• local development guide
• testing guide
• roadmap
• security documentation

The API reference covers the main public package APIs including PageHeaderPlugin, Header, MetadataEntry, CompactHeader, HasPageHeader, HeaderOptions, and the package enums.

Documentation deployment

Documentation builds are now validated in GitHub Actions and automatically deployed from the 2.x branch.

Manual documentation deployment through workflow_dispatch is also supported.

Expanded test coverage

Navigation behavior is covered across PHP and browser tests, including:

• breadcrumbs inside, outside, and hidden
• native Page/Resource sub-navigation
• record sub-navigation
• ManageRelatedRecords
• Relation Manager coexistence
• SPA navigation
• compact-mode visibility
• desktop tabs and mobile dropdowns
• light and dark themes
• Livewire updates
• keyboard focus
• layout stability

Upgrade

Update the package:

composer update mortalkiller/filament-page-header

Then republish Filament assets:

php artisan filament:assets

Republishing assets is important because this release includes updated CSS and JavaScript for header navigation.

Compatibility

Filament Page Header 2.x supports:

• Filament ^4.12.6 || ^5.8.1
• PHP ^8.3
• Laravel 12 and 13

Full changelog

v2.2.0...v2.3.0

---

This discussion was created from the release v2.3.0.