README

A Filament v5 plugin that replaces the default dashboard widget grid with a CSS Grid dense-packed masonry layout — no DOM height measurements, no JavaScript layout engine, no gaps.

Requirements

• PHP 8.3+
• Laravel 12+
• Filament 5.x

Installation

composer require secretninjas/filament-masonry

Setup

1. Register the plugin

Add MasonryPlugin to every panel that should use masonry dashboards:

use SecretNinjas\FilamentMasonry\MasonryPlugin;

->plugins([
    MasonryPlugin::make(),
])

The defaults are ['default' => 1, 'sm' => 2, 'xl' => 4]. Override with ->columns([...]) if you need different breakpoints:

MasonryPlugin::make()
    ->columns(['default' => 1, 'lg' => 3, '2xl' => 6])

2. Enable masonry on your Dashboard page

Add HasMasonryDashboard to any Dashboard page class:

use SecretNinjas\FilamentMasonry\Concerns\HasMasonryDashboard;

class Dashboard extends BaseDashboard
{
    use HasMasonryDashboard;

    // ... existing getWidgets(), getColumns(), etc.
}

That's it. No other Dashboard changes required.

3. Size your widgets (optional but recommended)

Add HasMasonryLayout to each widget to control how many grid columns and rows it occupies:

use SecretNinjas\FilamentMasonry\Concerns\HasMasonryLayout;
use SecretNinjas\FilamentMasonry\Enums\WidgetSize;

class RevenueWidget extends Widget
{
    use HasMasonryLayout;

    protected static WidgetSize $size = WidgetSize::Large;
    protected static int $order = 10;
}

Widgets without the trait continue to work — they fall back to their existing $columnSpan value, treated as 1 row.

Widget sizes

Size	Columns	Rows	Use for
Small	1	1	KPI card, compact list
Medium	2	1	Standard table, chart
Large	3	2	Tall table, multi-row chart
FullWidth	4	1	Stats bar, wide summary table

Widget ordering

$order replaces Filament's $sort when the trait is present. Lower = rendered first. The trait overrides getSort() so Filament's own widget-sort mechanism stays in sync.

How it works

The layout uses pure CSS:

display: grid;
grid-auto-flow: dense;
grid-template-columns: repeat(4, minmax(0, 1fr));
align-items: stretch;

Each widget wrapper receives inline grid-column: span X / span X; grid-row: span Y / span Y;. The dense packing algorithm fills gaps automatically without any JavaScript.

Responsive breakpoints are emitted as a scoped <style> block driven by the plugin's ->columns([...]) config.

Plugin configuration

All options are fluent and chainable on MasonryPlugin::make():

MasonryPlugin::make()
    ->columns(['default' => 1, 'sm' => 2, 'xl' => 4])
    ->stretchWidgets()       // default: true  — see below
    ->useCssMasonry(false)   // default: false — see below

->stretchWidgets(bool $stretch = true)

Controls whether widgets fill the full height of their grid cell.

• true (default) — align-items: stretch on the grid. Widgets and their inner sections stretch to match the tallest widget in a row. Great for dashboards where visual alignment matters.
• false — align-items: start on the grid. Each widget takes its natural content height. Row height is still set by the tallest widget, but shorter widgets won't stretch to match.

MasonryPlugin::make()
    ->stretchWidgets(false)  // cards take natural height

->useCssMasonry(bool $enabled = true)

Switches from the CSS Grid dense algorithm to the native CSS Masonry spec (grid-template-rows: masonry).

Experimental — as of 2026, supported only behind feature flags in Chrome and Firefox. Not in Safari stable. Do not use in production.

When enabled, row spans (grid-row: span X) are omitted from widget wrappers — the browser handles vertical placement automatically based on actual content height. Column spans still apply.

The rule is emitted inside @supports (grid-template-rows: masonry) { ... }, so the standard dense grid is used as a fallback on unsupported browsers:

/* Browsers that support native masonry */
@supports (grid-template-rows: masonry) {
    .fi-masonry-grid { grid-template-rows: masonry; }
}

To test in Chrome: enable chrome://flags/#enable-experimental-web-platform-features. To test in Firefox: set layout.css.grid-template-masonry-value.enabled = true in about:config.

MasonryPlugin::make()
    ->useCssMasonry()   // enable for experimentation

Architecture for future features

The package is designed to support these features in future versions without breaking changes:

• Drag & drop — swap widget $order values and persist per user
• User-specific layouts — store (user_id, widget_class, cols, rows, order) in a masonry_layouts table
• Collapsible widgets — toggle rows between 0 and the default via Alpine
• Dashboard templates — named presets of [widget => size] maps
• Tenant-specific dashboards — scope the layout table by tenant_id
• Widget groups — render a MasonrySection that spans multiple cells

Testing

Tests live in the consuming application. After installing the package, add tests that cover:

• Your widget classes using HasMasonryLayout — verify getMasonryColumns(), getMasonryRows(), getMasonryOrder()
• Your Dashboard page using HasMasonryDashboard — verify getWidgetsContentComponent() returns a MasonryGrid
• The MasonryGrid component — verify getBaseGridStyle() and getResponsiveStyles() output

php artisan test --filter=Masonry