v2.4.0

[mortalkiller]

Filament Page Header v2.4.0

Filament Page Header 2.4 adds native page action positioning and compact-mode action visibility controls while preserving Filament's existing action system.

Existing headers keep their current behavior by default. The new action controls are opt-in and fully backwards compatible with the 2.x line.

What's new

Native action positioning

Page header actions can now be positioned using a typed API:

use MortalKiller\FilamentPageHeader\Enums\HeaderActionsPosition;

Header::make()
    ->actionsPosition(HeaderActionsPosition::Below);

Available positions:

• HeaderActionsPosition::Start
• HeaderActionsPosition::End — default behavior
• HeaderActionsPosition::Below

Desktop positioning uses logical start/end alignment and supports RTL layouts.

Mobile keeps the existing full-width action area regardless of the configured desktop position.

Compact action selection

Compact headers can now choose which native Filament page actions remain visible:

use MortalKiller\FilamentPageHeader\CompactHeader;

Header::make()
    ->compact()
    ->whenCompact(
        fn (CompactHeader $compact) => $compact
            ->actions([
                'save',
                'approve',
            ])
    );

Action identifiers use the native Filament action name rather than the displayed label.

The inverse API is also available:

Header::make()
    ->compact()
    ->whenCompact(
        fn (CompactHeader $compact) => $compact
            ->hideActions([
                'delete',
                'duplicate',
            ])
    );

The last action-selection call wins.

Special cases:

->actions([])

hides all native actions in compact mode.

->hideActions([])

keeps all native actions.

Without action configuration, all actions allowed by Filament remain visible, preserving the existing package behavior.

Native Filament behavior preserved

Action control remains presentation-only.

The package continues to use the original cached Filament action instances and preserves:

• action authorization and visibility
• disabled states
• original action ordering
• nested ActionGroup structures
• dropdown actions
• button groups
• confirmation dialogs
• actions containing forms
• form submission targets
• render hooks around native page actions
• Livewire behavior
• keyboard focus and active interactions
• SPA navigation

Actions are not cloned or rendered separately between expanded and compact states.

Compact transitions do not send additional Livewire requests.

Action groups

Compact filtering works recursively with native Filament action groups.

When only selected child actions remain, the original group structure is preserved.

Groups that become empty in compact mode are removed from the presentation instead of leaving empty dropdowns or controls.

Nested groups and teleported dropdown positioning are also supported.

Improved interaction handling

This release adds dedicated handling for action-heavy headers, including:

• preserving an already-open dropdown while entering compact mode
• keeping a focused action available until focus moves away
• preserving modal and action-form state during compact transitions
• recalculating empty action groups after Livewire visibility changes
• cleaning up action presentation state during SPA navigation

Documentation

Added documentation for native action control, including:

• action positioning
• compact inclusion and exclusion
• action naming
• groups and dropdowns
• forms and modals
• authorization behavior
• custom action-view considerations
• responsive behavior

The README and API reference have also been updated.

Full documentation:

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

Testing

The feature is covered across PHP, JavaScript and browser tests.

Browser coverage includes:

• Start, End, and Below positioning
• LTR and RTL layouts
• mobile action layouts
• compact inclusion and exclusion
• individual actions
• nested action groups
• button groups
• dropdown actions
• teleported dropdown positioning
• hidden and unauthorized actions
• disabled actions
• render hooks
• keyboard focus
• action forms
• confirmation dialogs
• Livewire visibility changes
• SPA navigation
• expanded/compact transitions

The compatibility matrix was validated against the supported Filament 4 and Filament 5 lines.

Compatibility

Filament Page Header 2.x continues to support:

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

Upgrade

Update normally with Composer:

composer update mortalkiller/filament-page-header

Then republish Filament assets:

php artisan filament:assets

Republishing assets is required because this release includes updated CSS and JavaScript for native action control.

No application code changes are required unless you want to use the new functionality.

Full changelog

v2.3.2...v2.4.0

---

This discussion was created from the release v2.4.0.