Filament Kanban Laravel Package

Getting Started

mokhosh/filament-kanban drops a drag-and-drop board into a Filament panel. It ships no tables of its own — it reads and writes columns on a model you already have, which is why setup is mostly wiring.

1. composer require mokhosh/filament-kanban
2. Add (or confirm) two columns on the model you want to board-ify: one holding the column/status value, one holding an integer position within that column.
3. Generate a page and extend the package base class:

class TasksKanban extends \Mokhosh\FilamentKanban\Pages\KanbanBoard
{
    protected static string $model = Task::class;
    protected static string $statusEnum = TaskStatus::class; // backed enum, or use a status attribute
    protected static string $recordSortAttribute = 'sort';
}

4. Register the page in your panel provider (or let auto-discovery find it) and visit /admin/tasks-kanban.

Where to look first: the base KanbanBoard class itself (that is the real API surface — every hook, property, and view name lives there), then the published Blade views under resources/views/vendor/filament-kanban. The README covers the happy path; the base class covers everything you will actually need.

First use case: a Task with Todo / Doing / Done, dragged between columns, with the new status and order persisted on drop. Confirm that write happens before you build anything on top of it — if the enum or sort attribute is misconfigured, the board renders fine and silently no-ops on drop.

Implementation Patterns

Enum columns vs. attribute columns. The enum route is cleaner (type safety, labels for free) and is what most projects should use. Fall back to a plain status attribute + custom column list when statuses come from a database table, are per-tenant, or are workflow-driven rather than hard-coded.

Side effects belong in a hook, not an observer. Status changes triggered by drag-and-drop fire the same model events as any other save, so an observer works — but board-specific concerns (re-sorting, toast notifications, "moved to Done" timestamps) are easier to keep in the page's status-change / sort-change hook, where you still have the old and new values. Overriding those hooks is the single most common customization.

Custom card markup. Publish the views and override the record/card partial rather than trying to configure card content through properties. Keep the card Blade file lean — it renders once per record per column, so an accidental lazy-loading relationship or $record->comments->count() inside it will produce an N+1 the moment a board exceeds a few dozen cards.

Scoping and multi-tenancy. Override the query the board uses (getRecords() and friends) to constrain by tenant, team, or assignee. Boards are conventionally one page per scope; when you need the same board inside a resource (e.g. tasks for a project), mount it as a relation-scoped page rather than duplicating the board class.

Multiple boards, one model. Keep a separate page class per board and give each its own sort scope, or your sort integers from board A will interleave with board B. If they must share a table, prefix the sort attribute or filter by a board discriminator in the query.

Permissions. The board has no built-in authorization beyond Filament's page visibility. Gate the page with canView(), and for read-only roles either hide the page or accept that drags will attempt a write — check update on the model inside your status-change hook and abort there if you need a soft lock.

Testing. These boards are Livewire components; call the move/handle-drop method directly in a Livewire test and assert the model's status and sort columns. That is far more stable than trying to simulate HTML5 drag events.

Gotchas and Tips

• v2.11.0 changed method signatures (PR #80). This package is designed to be subclassed, so if you have overridden base methods, re-check your signatures against the new base class. PHP fatals on incompatible overrides — this is the one item in this release that can bite you on upgrade. The rest of the release is two bug fixes (#82) and Dependabot CI bumps with no runtime effect.
• Sort values must be contiguous per column. Sparse or duplicated integers produce non-deterministic ordering after a drop. Re-index the target column on every move, inside a transaction with lockForUpdate — concurrent drags by two admins will otherwise collide.
• A backed enum is expected, not a plain enum or string constant. Mismatched enum types are the most common cause of "the board renders but drops do nothing" — the cast fails silently against the status column.
• Full-page re-render on drop. The board refreshes after each move. On boards with hundreds of cards, cap records per column or add polling carefully; unpaginated boards get noticeably janky.
• Publish and clear. After vendor:publish of the views/assets, run php artisan view:clear — stale compiled views are the usual explanation for "my override isn't showing up."
• Livewire errors are quiet. When a drop silently snaps back, open the browser console and check the network response for the Livewire update; a 403 (policy) or a 500 (cast/mass-assignment) is almost always the cause, not the JS.
• Pin to your Filament major. Filament v3 vs v4 compatibility is not automatic across this plugin's range; lock the constraint and test the upgrade before bumping.
• Extension points worth knowing: the published Blade views, the record/card partial, the status-change and sort-change hooks, and the query method. Between those four you can cover nearly every requirement without forking; forking is a last resort because the upstream is actively patched.