README

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

🎯 Simple Integration - Add navigation with just a trait
🎨 Filament Native - Uses Filament's action system and styling
⚙️ Configurable - Customize ordering column and directions
🚀 Performance Optimized - Efficient database queries
🎭 Smart States - Automatically disables buttons at boundaries
📱 Responsive - Works beautifully on all devices

Requirements

PHP ^8.1
Laravel ^10.0
Filament ^3.0

Demo

Installation

Install the package via Composer:

composer require nben/filament-record-nav

Publish the configuration file (optional):

php artisan vendor:publish --tag=filament-record-nav-config

Quick Start

1. Add the trait to your Filament resource pages

Add the WithRecordNavigation trait to your ViewRecord or EditRecord pages:

<?php

namespace App\Filament\Resources\PostResource\Pages;

use App\Filament\Resources\PostResource;
use Filament\Resources\Pages\ViewRecord;

use Nben\FilamentRecordNav\Concerns\WithRecordNavigation;

class ViewPost extends ViewRecord
{
    use WithRecordNavigation;
    
    protected static string $resource = PostResource::class;
}

2. Add navigation actions to your page

Add the navigation actions to your page's action array:

<?php

namespace App\Filament\Resources\PostResource\Pages;

use App\Filament\Resources\PostResource;
use Filament\Resources\Pages\ViewRecord;

use Nben\FilamentRecordNav\Actions\NextRecordAction;
use Nben\FilamentRecordNav\Actions\PreviousRecordAction;

use Nben\FilamentRecordNav\Concerns\WithRecordNavigation;

class ViewPost extends ViewRecord
{
    use WithRecordNavigation;
    
    protected static string $resource = PostResource::class;
    
    protected function getHeaderActions(): array
    {
        return [
            PreviousRecordAction::make(),
            NextRecordAction::make(),
            // ... your other actions
        ];
    }
}

That's it! Your Filament resource pages now have beautiful next/previous navigation buttons.

Configuration

The package comes with sensible defaults, but you can customize the behavior by publishing and modifying the configuration file:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Default Navigation Column
    |--------------------------------------------------------------------------
    | 
    | This column will be used to determine the order of records
    | for navigation. Common choices: 'id', 'created_at', 'updated_at'
    |
    */
    'order_column' => 'id',

    /*
    |--------------------------------------------------------------------------
    | Navigation Directions
    |--------------------------------------------------------------------------
    |
    | Define the sort directions for previous and next navigation
    |
    */
    'previous_direction' => 'desc',
    'next_direction' => 'asc',
];

Advanced Usage

Custom Navigation Logic

You can override the navigation methods in your page class for custom behavior:

<?php

namespace App\Filament\Resources\PostResource\Pages;

use App\Filament\Resources\PostResource;
use Filament\Resources\Pages\ViewRecord;

use Illuminate\Database\Eloquent\Model;
use Nben\FilamentRecordNav\Concerns\WithRecordNavigation;

class ViewPost extends ViewRecord
{
    use WithRecordNavigation;
    
    protected static string $resource = PostResource::class;
    
    // Custom logic for finding the previous record
    protected function getPreviousRecord(): ?Model
    {
        return $this->getRecord()
            ->newQuery()
            ->where('status', 'published') // Only navigate through published posts
            ->where('created_at', '<', $this->getRecord()->created_at)
            ->orderBy('created_at', 'desc')
            ->first();
    }
    
    // Custom logic for finding the next record
    protected function getNextRecord(): ?Model
    {
        return $this->getRecord()
            ->newQuery()
            ->where('status', 'published') // Only navigate through published posts
            ->where('created_at', '>', $this->getRecord()->created_at)
            ->orderBy('created_at', 'asc')
            ->first();
    }
}

Custom Record URLs

By default, the navigation uses the view route. You can customize this:

<?php

namespace App\Filament\Resources\PostResource\Pages;

use App\Filament\Resources\PostResource;
use Filament\Actions;
use Filament\Resources\Pages\EditRecord;

use Illuminate\Database\Eloquent\Model; 
use Nben\FilamentRecordNav\Concerns\WithRecordNavigation;

class EditPost extends EditRecord
{
    use WithRecordNavigation;

    protected static string $resource = PostResource::class;

    protected function getRecordUrl(Model $record): string
    {
        return static::getResource()::getUrl('edit', ['record' => $record]);
    }
}

Customizing Action Appearance

You can customize the appearance of navigation buttons:

protected function getHeaderActions(): array
{
    return [
        PreviousRecordAction::make()
            ->label('← Previous')
            ->color('secondary')
            ->size('sm'),

        NextRecordAction::make()
            ->label('Next →')
            ->color('secondary')
            ->size('sm'),
    ];
}

Working with Different Resource Types

Edit Pages

The trait works seamlessly with edit pages:

<?php

namespace App\Filament\Resources\PostResource\Pages;

use App\Filament\Resources\PostResource;
use Filament\Resources\Pages\EditRecord;
use Nben\FilamentRecordNav\Actions\NextRecordAction;
use Nben\FilamentRecordNav\Actions\PreviousRecordAction;
use Nben\FilamentRecordNav\Concerns\WithRecordNavigation;

class EditPost extends EditRecord
{
    use WithRecordNavigation;
    
    protected static string $resource = PostResource::class;
    
    protected function getHeaderActions(): array
    {
        return [
            PreviousRecordAction::make(),
            NextRecordAction::make(),
        ];
    }
}

Multiple Resource Types

You can use the same navigation pattern across different resources:

// For Users
class ViewUser extends ViewRecord
{
    use WithRecordNavigation;
    // ... configuration
}

// For Orders  
class ViewOrder extends ViewRecord
{
    use WithRecordNavigation;
    // ... configuration
}

Navigation Behavior

Smart Button States

Previous Button: Automatically disabled when viewing the first record
Next Button: Automatically disabled when viewing the last record
Visual Feedback: Disabled buttons are visually distinct (gray color)

Performance Considerations

The package uses efficient database queries:

Only fetches the next/previous record when needed
Uses indexed columns for optimal performance
Minimal database overhead

Troubleshooting

Navigation Not Working

Ensure the trait is added: Make sure WithRecordNavigation trait is used in your page class
Check action registration: Verify that NextRecordAction and PreviousRecordAction are added to your getHeaderActions() method
Database ordering: Ensure your ordering column exists and has appropriate indexes

Custom Ordering Issues

If using a custom order column, make sure:

The column exists in your database table
The column is properly indexed for performance
The column has appropriate data types for comparison

Performance Issues

For large datasets:

Ensure your ordering column is indexed
Consider adding database indexes on frequently filtered columns
Override navigation methods to add appropriate where clauses

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

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

nben / filament-record-nav

Maintainers

Details