Filament Select Tree Laravel Package

Product Decisions This Supports

• Build vs. buy for hierarchical pickers. A nested, searchable, multi-select tree with branch selection, tag summaries, and disabled/hidden nodes is a multi-day frontend build (keyboard handling, search, expansion state, Filament design-system fidelity). This package collapses that into one field class, so the "build it ourselves" option can be closed quickly and the decision shifts to "which hierarchy semantics do we need?"
• Data-model decisions that outlive the UI. Two options encode real business rules, not cosmetics: isGroupedValue() (store the parent when all children are selected) versus storing individual leaves, and enableBranchNode() (is a parent a valid selection?). Choosing wrong creates downstream problems in reporting, facet counts, and re-assignment when the hierarchy changes. This is the highest-value conversation the package forces, and it belongs to the PM, not the developer.
• Roadmap unlocks for taxonomy and org-structure features. Category trees, department/cost-centre hierarchies, product classifications, region groupings, permission bundles, CMS section trees. If a roadmap item says "users should be able to assign records to any level of the category tree," this is the enabling component.
• Filter and reporting UX. The table-filter integration (including prepend for an "Uncategorized Records" node at -1) directly supports "show me records with no category" workflows — the query needed for backfill and data-hygiene dashboards during migrations.
• Scoping and access-control decisions. modifyQueryUsing lets you restrict the tree per tenant or per role. The strictNullParentRootNodes() toggle is a genuine policy choice: by default, children of filtered-out parents get promoted to root nodes (to avoid empty trees) — which may surface options a user shouldn't see. Worth an explicit decision, not a default.
• Retention and audit scope. withTrashed() lets soft-deleted categories stay visible and assignable; that's a compliance/retention stance, not a UI preference.
• Adoption sequencing. Versioned branches track Filament majors (4.x for Filament 4, 3.x for Filament 3), so the package doesn't gate a Filament upgrade — it just adds a parallel upgrade task.

When to Consider This Package

Adopt when most of these hold:

• You are already on Filament 3 or 4 — this is a Filament form-field package and has no value outside that stack.
• Your hierarchy is moderate and mostly read-shaped: dozens to low thousands of nodes, browsed rather than edited.
• You need selection, not tree management. This is a picker; create/rename/reorder/drag-drop lives in your own resource.
• Selection semantics (branch-selectable or not, store-parent-or-leaves) can be decided once and documented.
• You want low lock-in: one field in one form schema, replaceable by a native Select in an afternoon if it disappoints.

Look elsewhere — or budget for a custom field — when:

• You need tree editing in place: drag-and-drop ordering, inline create, move-node, bulk re-parenting.
• Your tree is large or deep enough to need async/lazy loading; the field fetches and filters in PHP, and withCount() / storeResults() add work per render. Benchmark against production data first.
• Hierarchies are per-user or per-tenant dynamic with heavy permission filtering — the root-promotion default and query hooks will need careful review, and edge cases here are the package's least-tested surface.
• You are not on Filament, or you are pinned to a Filament major with no matching branch.
• You need audited hierarchy history (effective-dated trees, "what category was this in last quarter"). The package stores no hierarchy history; that's your model's job.

Two dependency risks to accept knowingly: it is a single-maintainer package (plus an upstream JS library, treeselectjs) and has zero Packagist dependents — normal for a UI field in app code, but it means no downstream ecosystem is absorbing the upgrade pain with you. The release history is a mitigating signal: active patch cadence, SPA-mode fix, strict-root edge-case fix, and dependabot hygiene all suggest the maintainer responds.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed UI component for our admin panel that gives users a proper drill-down selector for anything with a hierarchy — categories, departments, regions. It replaces something we would otherwise build and maintain ourselves, at an estimated one to two weeks of engineering plus permanent upkeep. Because it's a single form field, our exposure is small: if it doesn't work out, we swap it for a plain dropdown without touching the data model. The one decision we need from the business is how selections are recorded — do we assign records to a top-level category or to every sub-category? That choice affects reporting and how much work a re-categorisation becomes later, so it's worth thirty minutes of product time now.

For engineering: Filament-native field, Composer install plus filament:assets, works with BelongsTo and BelongsToMany relationships, raw queries, or a fully hand-built tree array via getTreeUsing. Covers search, branch-node selection, disabled/hidden options, soft deletes, counts, static lists, and table filters — all of which we would otherwise hand-roll. Version branches align with Filament majors, so it won't block an upgrade. Known constraints: one maintainer, an upstream JS dependency, no ecosystem dependents, and PHP-side tree construction that needs benchmarking on our largest hierarchy before we commit. Recommended posture: adopt behind a single field, verify against real data volume, and keep the option to fall back to a native Select if behaviour or maintenance disappoints.

Ask: approval to trial on one taxonomy form this sprint, with a half-hour product decision on branch-vs-leaf storage before implementation.