Download the PHP package nben/filament-record-nav without Composer

Filament Record Navigation

A Laravel package that adds elegant next/previous record navigation to your Filament PHP admin panels. Navigate seamlessly between records with intuitive navigation buttons.

Features

• Zero-config integration - drop two actions into getHeaderActions() and you're done
• No trait required - actions work out of the box without any page class changes
• Filament native - extends Filament's Action class, all fluent methods work
• Configurable - set ordering column and direction globally via config
• Fully overridable - add the trait and override any method for custom query logic
• Page-type aware - choose view, edit, or any custom route as the target page per action
• Custom routes - navigate to any route registered in your resource's getPages()
• Future-proof - depends only on Filament's stable $livewire injection API
• Smart boundaries - buttons auto-disable and turn gray at the first/last record
• Optimised queries - each action fires exactly one database query per render

Requirements

• PHP ^8.2
• Laravel ^10.0 | ^11.0 | ^12.0 | ^13.0
• Filament ^4.0 | ^5.0

Demo

Live site: rnd.nben.com.np

Installation

Install the package via Composer:

Optionally publish the config file to customise the order column and sort directions:

Quick Start

Add the two actions to getHeaderActions() on any ViewRecord or EditRecord page. No trait required - this is all you need for the default behaviour.

Out of the box the actions will:

• Order records by the order_column defined in config (default: id)
• Render as outlined primary buttons with chevron icons
• Disable and turn gray when there is no adjacent record (first / last)
• Navigate to the view page of the adjacent record

Navigating to the Edit Page

Use ->navigateTo() with the NavigationPage enum to control which page type the action redirects to. Each action can target a different page type independently.

Or mix them:

Navigating to a Custom Route

If your resource registers custom page routes beyond the standard view and edit, use NavigationPage::custom() to navigate to them by route name.

First, register your custom page in the resource's getPages():

Then pass the route name string to NavigationPage::custom():

The route name passed to custom() is forwarded directly to Resource::getUrl($routeName, ['record' => $record]), so it must exactly match a key in your resource's getPages() array.

Note: Custom routes still benefit from the same smart boundary detection - buttons auto-disable and turn gray when there is no adjacent record to navigate to.

Customising Button Appearance

Both actions extend Filament's Action class directly, so every fluent method from the Filament Actions docs works as normal:

Custom Navigation Logic

For custom query logic - filtering by status, scoping to a tenant, ordering by a different column - add the WithRecordNavigation trait to your page class and override the methods you need.

The trait is optional. Only add it when the default config-driven query is not sufficient.

Filtering which records can be navigated

Overriding the navigation URL

Override getRecordNavigationUrl() to fully control where the action redirects. The $page parameter is either a NavigationPage enum case or a CustomNavigationPage value object - both expose a ->value string with the route name.

Or respect whatever page type was passed, including custom routes:

Strict typing with the contract (optional)

If you want IDE autocompletion and static analysis support (PHPStan / Psalm), declare implements HasRecordNavigation alongside the trait:

Note: The actions use method_exists() rather than instanceof to detect navigation methods. This means declaring implements is optional - the actions will call your overridden methods correctly either way. The interface is purely for your own type-safety tooling.

Configuration

Architecture

How it works

When a page renders, Filament evaluates each action's color(), disabled(), and url() closures. Each closure receives the Livewire component instance via Filament's $livewire utility injection - a stable, first-class API that is not expected to change between Filament versions.

Inside each closure, ResolvesAdjacentRecord::getCachedRecord() is called. On the first call it resolves the adjacent record (via the page's override or the config fallback), stores it in $resolvedRecordCache, and returns it. The second and third closure calls read from the cache - so only one database query fires per action per render, regardless of how many closures need the result.

When navigateTo() receives a NavigationPage enum case or a CustomNavigationPage value object, both expose the same ->value string property. resolveUrl() calls Resource::getUrl($page->value, ['record' => $record]) on either type without any instanceof branching, keeping the URL resolution path simple and uniform.

No internal Filament lifecycle hooks (configureAction(), bootUsing(), etc.) are used anywhere in the package.

Troubleshooting

Buttons are always disabled (gray)

• Confirm the order_column in config matches an actual column on your table.
• If using a timestamp column (created_at), ensure records have distinct values - records with identical timestamps will not find each other.
• If you have overridden getPreviousRecord() / getNextRecord(), add a temporary \Log::info(...) inside them to confirm they are being called and the query returns what you expect.

Custom filter overrides are being ignored

• Confirm the WithRecordNavigation trait is present on the page class with use WithRecordNavigation;.
• Confirm the method signatures match exactly: public function getPreviousRecord(): ?Model and public function getNextRecord(): ?Model.
• Confirm use Illuminate\Database\Eloquent\Model; is imported at the top of the page class.

Wrong page type after navigation

• Use ->navigateTo(NavigationPage::Edit) on the action for the edit page.
• Use ->navigateTo(NavigationPage::custom('your-route-name')) for a custom route.
• Confirm the route name string passed to custom() exactly matches a key in your resource's getPages() array.
• Or override getRecordNavigationUrl() in the trait to always return the route you want.

InvalidArgumentException or route not found after using NavigationPage::custom()

• The route name passed to custom() must exactly match a key in getPages(), including hyphens and casing.
• Double-check: 'verified-view' => ViewVerifiedUser::route('/{record}/verified') in getPages() matches NavigationPage::custom('verified-view') on the action.

Performance on large tables

• Add a database index on the order_column.
• Override getPreviousRecord() / getNextRecord() to add where() scopes that narrow the result set before the adjacent record query runs.

Upgrade Guide (from v2.0.x)

v2.1.0 is fully backward compatible with v2.0.0. No changes are required to existing code. The only addition is the NavigationPage::custom() named constructor and the CustomNavigationPage value object that supports it.

Upgrade Guide (from v1.x)

v2.0.0 is a full rewrite for Filament v4/v5. Summary of breaking changes:

Migration steps:

1. Remove configureAction() from any page classes that overrode it - it is no longer used.
2. Rename getRecordUrl(Model $record) to getRecordNavigationUrl(Model $record, NavigationPage|CustomNavigationPage $page) wherever you defined it. Import both NavigationPage and CustomNavigationPage at the top of the file.
3. Add ->navigateTo(NavigationPage::Edit) to any actions that previously pointed to edit routes via getRecordUrl().
4. The trait is now optional - you can remove use WithRecordNavigation from pages that relied only on the default behaviour (no method overrides).

Contributing

Contributions are welcome. Please open an issue before submitting a pull request for major changes so we can discuss the approach first.

License

This package is open-sourced software licensed under the MIT license.

Credits

• Leandro Ferreira – Original Idea / Blog Post – leandrocfe
• Nben Malla – Package Developer – nb3n

Support

• Issues: GitHub Issues
• Source: GitHub Repository

Made with ❤️ for the Filament PHP community