Filament Kanban Laravel Package

Getting Started

Filament Kanban is a board UI for Filament 5 / Livewire 4.1+ — think of it as a "table-like" component whose rows are cards and whose groups are columns, with drag-and-drop between them. The fastest path to value is to put it on a model that already has a status column and a sort column.

1. Confirm the stack: Filament 5 and Livewire 4.1+ are hard requirements. If you're mid-upgrade from Filament 3/4, do that first — this package won't be your blocker, but it will be unusable until Livewire 4.1 is in place.
2. composer require the package, then publish configuration and assets. The release ships compiled package CSS, so asset publishing is a real install step, not an optional one — a board that renders unstyled is almost always a missing vendor:publish.
3. Skim the README's installation section, then jump straight to the fictional demo data and screenshots — they're in the standard Filament theme, so you can compare your output against them one-to-one when something looks off.
4. First use case to build: a Task model with a status enum and an order integer. Wire the board to that, render a card with an infolist schema, and get a single drag between two statuses persisting. Resist adding filters, pagination, and custom views until that loop works.

Where to look first, in order: README install → card schema section → transitions/drag section → actions. The card schema and actions are where you'll spend 80% of your time.

Implementation Patterns

Board as a page or a resource page. The natural fit is a custom Filament page (or a relation manager-style page on a Project), with the board occupying the content area. Keeping it as a dedicated page rather than bolting it onto a resource list avoids fighting the table's own state (filters, search, pagination) against the board's.

Columns from a backed enum. Drive column definitions from the same enum that backs your status cast. This keeps labels, colors, and transition rules in one place and means adding a status is a one-line change. Map the enum cases to columns in a loop rather than hand-writing each column.

Card schema = infolist schema. The package's infolist-based card schema is the most important integration point. Build cards with the same entry components you already use (TextEntry, ImageEntry, IconEntry, badges), and — critically — reuse the schema from your resource's infolist so the board and the edit page never drift. Because it's a schema and not a Blade partial, you get Filament's state handling and dark mode for free.

Layout presets, then custom views. Default / Compact / Flat / Accent will cover most dashboards; switch presets rather than hand-rolling CSS. Only reach for a custom card view when you need genuinely custom markup, and accept that you're now maintaining that markup against future package releases.

Shared action forms. The "shared action forms" feature is the one to lean on hardest: define a card action's form once and reuse it for column actions and your resource's edit action. In practice this means extracting form schemas into a static method on the resource or a dedicated schema class, then passing it to both. This is what stops the board's quick-edit from silently diverging from the real edit form.

Transitions as the authorization boundary. Drag-and-drop should not be a raw status assignment. Use the transitions feature to encode allowed moves (e.g. draft → review but not draft → done) and throw/deny there. This is also the right place to hang side effects — notifications, timestamps, audit entries — so they fire identically whether the move came from a drag or a column action.

Ordering strategies. Persisted ordering plus move-to-top behavior covers the common "new item appears at the top" UX. Decide early whether order is per-column or global: per-column is simpler for drag-and-drop and matches the visual model; global ordering makes cross-column moves ambiguous. Store it in a dedicated integer column and treat it as package-owned — don't also use it as a business-level priority.

Pagination: pick one, deliberately. Progressive loading suits boards where users scroll a few columns and want a single continuous feel; independent column pagination suits boards where individual columns are huge and users jump between them. Independent pagination gives better per-column control but makes cross-column drag more surprising. "Complete filtered totals" means counts stay accurate under filters, which is the thing users notice first — verify it against your own filter logic.

Filters. Native Filament filters mean the board's filter bar behaves like a table's. Reuse your resource's table filters by extracting them to a shared class. Note the interaction with drag-and-drop: a filtered board hides cards, so dropping into a filtered column can place a card relative to a record the user cannot see. Either disable drag under active filters or accept the "it moved somewhere invisible" behavior consciously.

Gotchas and Tips

• Publishing assets after every upgrade. Compiled CSS ships with the package, but your published copies don't update themselves. Add vendor:publish --force for the package tag to your upgrade checklist, and clear view/config caches when the board looks "half-styled" after a version bump.
• Custom card views and Tailwind. If your app compiles Tailwind, classes used only inside a custom card view won't be generated unless the package's views directory is in your content paths. This is the single most common cause of "the card renders but looks wrong."
• Concurrent reordering. Two users dragging in the same column will race on the order column. Wrap reorder callbacks in a transaction and, for busy boards, consider a lockForUpdate or a version column. The package persists ordering; it doesn't adjudicate conflicts.
• N+1 in the card schema. Infolist entries that touch relations (assignee, tags, comment counts) will lazy-load per card. Eager-load everything the card schema reads in the board's query — with progressive loading this hides the problem at first and bites you when someone turns pagination off.
• Move-to-top across pages. With independent column pagination, "move to top" is only unambiguous when the target column is sorted by the order column consistently. If you add a secondary sort (e.g. due date), the top of page 1 isn't the top of the column. Keep exactly one ordering authority.
• Enum + transition mismatch. If your transitions config and your enum disagree, drags fail silently or succeed wrongly. Write a small test that asserts every allowed transition in the config is a legal enum case pair.
• Authorization granularity. Column actions and card actions each need policies. Check that a user who can view a board can't drag a card they can't update — the board's UI affordances and your policies are two separate layers.
• Pagination choice is a migration, not a toggle. Switching between progressive loading and per-column pagination changes scroll position, drag targets, and how totals read. Pick one per board and keep it.
• Testing. The package's 85 tests / 861 assertions are reassuring for the package, not for your integration. Write Livewire tests for your board page: assert a drag persists status and order, assert a disallowed transition is rejected, assert filtered totals match. These are cheap and catch every package upgrade regression.
• Extension points to prefer, in order: shared action form schemas → infolist card schema → layout presets → custom card views. Each step down costs more maintenance across releases.
• Packagist registration is tracked separately from this GitHub release — if composer require can't resolve it yet, use a VCS repository entry in composer.json rather than assuming you've misconfigured something.