Filament Palette Laravel Package

Getting Started

1. Install / upgrade into the app that owns the Filament panel:

   composer require xuanpablo/filament-palette:^2.3
   

2. Publish the config if you haven't already (php artisan vendor:publish for the palette config tag) and confirm it lands in config/. Every behaviour discussed below is driven from this file, so it's the first place to look.
3. Register the plugin on the panel you actually use (usually app/Providers/Filament/AdminPanelProvider.php), then clear cached config:

   php artisan config:clear && php artisan filament:optimize-clear
   

4. First use case: open the panel, hit the palette shortcut (typically Cmd/Ctrl + K), and jump to a resource or page by name. That single flow — keyboard-only navigation instead of sidebar clicking — is the 80% win; everything else is configuration on top of it.

After upgrading to 2.3, the new capability to try is global-search records: flip include_global_search_results to true on a staging panel and confirm records appear under their category beneath commands.

Implementation Patterns

Treat the palette as the panel's "jump to" layer. The realistic day-to-day pattern is: commands for destinations (resources, custom pages, dashboard), record search for entities. Keep the two visually distinct in your mental model — commands are static and cheap, records are a network round-trip.

Enabling record search (new in 2.3). Two preconditions, both silent if unmet:

• the config flag include_global_search_results is true, and
• the panel has a global search provider configured (the same one powering Filament's own global search).

When both hold, typing triggers a debounced $wire round-trip that fetches matching records and renders them under their category. Tune with:

'include_global_search_results' => true,
'global_search_results_limit'   => 10,   // default
'global_search_debounce_ms'     => 300,  // default

Tune the debounce, don't fight it. 300ms is a sensible default for human typing. Raise it (e.g. 400–500) on panels backed by large or remote databases where each round-trip is expensive; lower it only if you've measured that the request is trivially cheap. The limit is a render cap, not necessarily a query cap — assume the provider may fetch more than it shows.

Roll out per panel, not per app. If you run multiple panels (admin + a lighter tenant/app panel), enable record search only where the global search provider is already well-curated. A panel whose global search returns noisy results will produce a noisy palette, and the palette is the most visible surface in the UI.

Sequence the rollout: staging panel → internal users → production. This is explicitly what the release note asks for; the record-fetch UI is new client behaviour, so verify it renders correctly with your panel's asset pipeline (theme build, Vite, cached assets) before it reaches real users.

Keep an eye on the palette's command registrations as your app grows — adding many custom commands can crowd out record results in the list; the limit above only governs records.

Gotchas and Tips

• Off by default is deliberate. After upgrading, nothing changes until you set the flag. Don't assume the feature is broken when it doesn't appear — check the flag and the panel's global search provider, in that order.
• Smoke-test the client behaviour. The debounced $wire fetch is new front-end code in 2.3. Verify: typing quickly doesn't fire a request per keystroke, results replace rather than append across successive queries, and an empty query clears the record section cleanly.
• Authorization is the real risk. Records surfaced in the palette should respect the same policies as the rest of the panel. Confirm with a low-privilege user account that they can't see records they shouldn't — a global search provider is only as scoped as its query.
• Debounce ≠ cancellation on slow queries. If your provider is slow, in-flight requests can resolve out of order and briefly show stale results. Test on a realistically sized dataset, not a seeded dev DB with 20 rows.
• Config caching bites. Filament panels and package config are cached in production; changing include_global_search_results without php artisan config:clear (and your deploy's optimize step) will appear to do nothing.
• Asset rebuild after upgrade. If you compile a custom Filament theme, re-run your front-end build after bumping to 2.3 — the new record-fetch UI ships client assets, and a stale build is the most likely cause of "the flag is on but nothing appears."
• Debug by narrowing: if records don't show, first confirm the plain global search modal (outside the palette) returns results. That isolates provider/config problems from palette-specific ones.
• Extension point to watch: the package's command registration is where you should add your own entries rather than hard-coding links in views. Keeping custom commands in one place makes it trivial to reason about ordering alongside the new record category.
• Upgrade is non-breaking — ^2.3 is additive, so existing palettes behave identically until you opt in.