Grid Card layout

• Requirements
• Features
• Installation
  • Theme Source (Tailwind v4)
• Quick Start
• Card Rendering Modes
  • Mode 1: Structured Sections
    • Badge Format
  • Mode 2: Closure-based
  • Mode 3: Custom Blade View
  • Rendering Priority
• Configuration Reference
  • Grid Layout
  • Pagination
  • Bulk Selection
  • Record Click URL
• Plugin Configuration
• Configuration Cascade
• Default Config File
• Full Example
• How It Works
• Performance
• CSS Classes
• License

Replace any Filament resource's default list table with a responsive card/grid layout. Define how each record card looks using structured sections, a closure, or a custom Blade view — while keeping all of Filament's search, filters, sorting, pagination, bulk actions, and record actions working out of the box.

No need to rewrite your resource. The same table() definition powers both the grid and the standard table.

#Requirements

• PHP 8.4+
• Laravel 13+
• Filament 4+

#Features

• Responsive CSS grid — configurable columns per Tailwind breakpoint (default, sm, md, lg, xl, 2xl)
• Three card rendering modes — structured sections, closure-based, or custom Blade view
• Full table infrastructure reuse — search, filters, sorting, pagination, bulk selection, record actions, header actions, empty state all work without extra setup
• Configurable pagination — default records per page and page options at the page, plugin, or config level
• Bulk selection — checkboxes on each card, works with existing bulk actions
• Record actions — view, edit, delete, and custom actions render on each card
• Click-to-navigate — cards link to view/edit pages using the resource's existing record URL logic
• Badge support — render status badges with color on each card
• Performance optimized — content-visibility: auto skips rendering of offscreen cards, lazy-loaded images
• Dark mode support
• Plugin-level defaults — set grid columns, gap, and pagination globally for all grid list pages
• Three-level configuration cascade — page overrides plugin overrides config file

#Installation

composer require wezlo/filament-grid-list

Optionally register the plugin in your Panel Provider for global defaults:

use Wezlo\FilamentGridList\FilamentGridListPlugin;

->plugins([
    FilamentGridListPlugin::make()
        ->gridColumns(['default' => 1, 'sm' => 2, 'lg' => 3])
        ->gap(4)
        ->recordsPerPage(12)
        ->recordsPerPageOptions([12, 24, 48, 96]),
])

Optionally publish the config:

php artisan vendor:publish --tag=filament-grid-list-config

#Theme Source (Tailwind v4)

The package's Blade views use Tailwind utility classes. For Tailwind to detect them during your app's build, add the package's views as a @source in your Filament custom theme CSS file (usually resources/css/filament/admin/theme.css):

@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../vendor/wezlo/filament-grid-list/resources/views/**/*';

@custom-variant dark (&:where(.dark, .dark *));

If you don't have a custom theme yet, create one:

php artisan make:filament-theme

Then rebuild assets:

npm run build

Without this step, some Tailwind utilities used in the grid view may be missing from the compiled CSS.

#Quick Start

Add the HasGridList trait to your resource's ListRecords page and implement the gridList() method:

use Filament\Resources\Pages\ListRecords;
use Wezlo\FilamentGridList\Concerns\HasGridList;
use Wezlo\FilamentGridList\GridListConfiguration;

class ListProducts extends ListRecords
{
    use HasGridList;

    protected static string $resource = ProductResource::class;

    public function gridList(GridListConfiguration $config): GridListConfiguration
    {
        return $config
            ->gridColumns(['default' => 1, 'sm' => 2, 'lg' => 4])
            ->header(fn ($record) => $record->name)
            ->content(fn ($record) => Str::limit($record->description, 100))
            ->footer(fn ($record) => '$' . number_format($record->price, 2));
    }
}

That's it. The list page now renders as a card grid. Your existing table() definition continues to power filters, search, actions, and pagination.

#Card Rendering Modes

#Mode 1: Structured Sections

Build cards from discrete sections. Each receives the Eloquent record and returns a string or HtmlString. All sections are optional — use any combination.

public function gridList(GridListConfiguration $config): GridListConfiguration
{
    return $config
        ->image(fn ($record) => $record->thumbnail_url)
        ->header(fn ($record) => $record->name)
        ->badges(fn ($record) => [
            ['label' => $record->status->getLabel(), 'color' => $record->status->getColor()],
            ['label' => $record->category->name, 'color' => 'info'],
        ])
        ->content(fn ($record) => $record->short_description)
        ->footer(fn ($record) => '$' . number_format($record->price, 2));
}

#Badge Format

Badges can be either arrays or renderable Blade components:

// Array format (recommended)
['label' => 'Active', 'color' => 'success']

// Any renderable (Blade component, HtmlString, etc.)
view('components.my-badge', ['status' => $record->status])

Available badge colors: primary, secondary, success, danger, warning, info, gray.

#Mode 2: Closure-based

Return raw HTML for full control over the card body:

use Illuminate\Support\HtmlString;

$config->describeUsing(fn ($record) => new HtmlString("
    <div class='p-4'>
        <h3 class='font-semibold'>{$record->name}</h3>
        <p class='text-sm text-gray-500'>{$record->description}</p>
        <span class='text-lg font-bold'>\${$record->price}</span>
    </div>
"));

#Mode 3: Custom Blade View

Point to your own Blade view for maximum flexibility:

$config->cardView('products.grid-card');

The view receives three variables:

{{-- resources/views/products/grid-card.blade.php --}}
<div class="p-4">
    <img src="{{ $record->image_url }}" class="w-full h-48 object-cover rounded-lg" />
    <h3 class="mt-3 font-bold text-gray-900 dark:text-white">{{ $record->name }}</h3>
    <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">{{ $record->description }}</p>
    <div class="mt-3 flex items-center justify-between">
        <span class="text-lg font-semibold">${{ number_format($record->price, 2) }}</span>
        <span class="text-xs text-gray-400">{{ $record->created_at->diffForHumans() }}</span>
    </div>
</div>

#Rendering Priority

When multiple modes are configured, the first match wins:

1. cardView() (custom Blade view)
2. describeUsing() (closure)
3. Structured sections (header(), content(), etc.)
4. Fallback: displays the record's title via getTableRecordTitle()

#Configuration Reference

#Grid Layout

$config->gridColumns(['default' => 1, 'sm' => 2, 'md' => 3, 'lg' => 4])
       ->gap(6);  // Tailwind spacing unit (6 = 1.5rem)

Breakpoint keys follow Tailwind: default, sm, md, lg, xl, 2xl. The value is the number of columns at that breakpoint.

#Pagination

Set pagination on the grid config (overrides the table's defaults):

$config->recordsPerPage(24)
       ->recordsPerPageOptions([12, 24, 48, 96]);

Or configure it on your table() method as usual — the grid respects it:

public function table(Table $table): Table
{
    return $table
        ->columns([...])
        ->defaultPaginationPageOption(12)
        ->paginationPageOptions([12, 24, 48, 96]);
}

All Filament pagination modes (Default, Simple, Cursor) work.

Note: The 'all' page option is excluded from defaults to prevent page hangs on large datasets. Cards use content-visibility: auto for offscreen rendering optimization, but loading thousands of DOM nodes can still be slow. If you need it, opt in explicitly: ->recordsPerPageOptions([12, 24, 48, 'all']).

#Bulk Selection

Enabled by default when the table has bulk actions. Disable per-page with:

$config->selectable(false);

#Record Click URL

By default, cards link to the view/edit page using the resource's existing record URL logic (same as clicking a table row). Override per-page with:

$config->recordUrl(fn ($record) => route('products.show', $record));

#Plugin Configuration

Register the plugin in your Panel Provider to set defaults for all grid list pages in that panel:

use Wezlo\FilamentGridList\FilamentGridListPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentGridListPlugin::make()
                ->gridColumns(['default' => 1, 'sm' => 2, 'md' => 3, 'lg' => 4])
                ->gap(4)
                ->recordsPerPage(12)
                ->recordsPerPageOptions([12, 24, 48, 96]),
        ]);
}

#Configuration Cascade

Each setting resolves through a three-level cascade:

1. Page-level — values set in gridList() on the ListRecords page (highest priority)
2. Plugin-level — values set on FilamentGridListPlugin in the Panel Provider
3. Config file — values in config/filament-grid-list.php (lowest priority)

Page-level always wins. If not set, falls through to plugin, then config.

#Default Config File

// config/filament-grid-list.php
return [
    'grid_columns' => [
        'default' => 1,
        'sm' => 2,
        'md' => 3,
        'lg' => 4,
    ],
    'gap' => 4,
    'records_per_page' => 12,
    'records_per_page_options' => [12, 24, 48, 96],
];

#Full Example

use App\Enums\ProductStatus;
use Filament\Resources\Pages\ListRecords;
use Illuminate\Support\Str;
use Wezlo\FilamentGridList\Concerns\HasGridList;
use Wezlo\FilamentGridList\GridListConfiguration;

class ListProducts extends ListRecords
{
    use HasGridList;

    protected static string $resource = ProductResource::class;

    public function gridList(GridListConfiguration $config): GridListConfiguration
    {
        return $config
            ->gridColumns(['default' => 1, 'sm' => 2, 'md' => 3, 'xl' => 4])
            ->gap(6)
            ->recordsPerPage(24)
            ->recordsPerPageOptions([12, 24, 48])
            ->image(fn ($record) => $record->thumbnail_url)
            ->header(fn ($record) => $record->name)
            ->badges(fn ($record) => [
                ['label' => $record->status->getLabel(), 'color' => $record->status->getColor()],
                ['label' => $record->category->name, 'color' => 'info'],
            ])
            ->content(fn ($record) => Str::limit($record->description, 120))
            ->footer(fn ($record) => '$' . number_format($record->price, 2))
            ->selectable()
            ->recordUrl(fn ($record) => ProductResource::getUrl('view', ['record' => $record]));
    }
}

The resource's table() method stays unchanged — columns, filters, search, actions, and bulk actions all carry over to the grid view automatically.

#How It Works

• The HasGridList trait overrides content() on the ListRecords page to render a custom Blade view instead of the default EmbeddedTable
• The trait overrides makeTable() to apply pagination config from GridListConfiguration
• Records come from $this->getTableRecords(), which handles the full filtered/sorted/paginated query pipeline from Filament's InteractsWithTable trait
• The view initializes Filament's filamentTable() Alpine component for selection state management
• Search binds to wire:model.live.debounce on the existing tableSearch Livewire property
• Filters render using the table's filter trigger action and $this->getTableFiltersForm()
• Bulk selection uses toggleSelectedRecord() / isRecordSelected() from the filamentTable Alpine component — same API as the standard table
• Record actions are cloned per-record using $action->getClone() (same pattern as the standard table view)
• Pagination renders via <x-filament::pagination> with the paginator from getTableRecords()
• Cards use content-visibility: auto CSS so the browser skips layout/paint for offscreen cards

#Performance

• content-visibility: auto — offscreen cards skip layout and paint, keeping the page responsive even with many records
• Lazy-loaded images — card images use loading="lazy" so only visible images are fetched
• No 'all' by default — pagination defaults to [12, 24, 48, 96] to prevent DOM overload. Opt in to 'all' explicitly if needed
• Deferred loading support — respects Filament's wire:init="loadTable" for deferred table loading

#CSS Classes

All card elements use fi-grid-list-* prefixed classes for targeted styling:

Override any of these in your theme CSS to customize the card appearance.

#License

MIT