Filament Keyboard Shortcuts Laravel Package

Getting Started

This package layers keyboard-driven navigation and a command sheet onto Filament panels. The fastest path to value is to register the plugin on a panel, open the app, and press g — every sidebar item shows its chord as a badge (beside the icon when collapsed), and typing narrows the set. That single interaction is the core loop: g + letters to jump, ?/sheet for discovery, Esc to dismiss.

Where to look first:

1. The plugin registration on your panel provider — that is where panel-level options such as ->navigationHints(false) live.
2. The config file (publish it if the package ships one) for sheet behaviour, chord pill timing, and hint defaults.
3. The command sheet itself — it is the self-documenting surface; sections are grouped by navigation group, so a well-organised panel produces a well-organised sheet for free.
4. The README’s shortcut table for the default keys before you override anything.

First use case to wire up: navigate an existing admin panel without touching a resource. Press g, type the first letter of a page label, hit Enter if the prefix is ambiguous. Once that works, pin a chord on your busiest resource (see below) and verify the sidebar title/aria-description reflects it.

Implementation Patterns

Pinning a chord per resource or page. Declare protected static ?string $keyboardShortcut = 'u'; on the resource/page class, or implement public static function getKeyboardShortcut(): ?string when the chord must be computed (per-tenant, per-role, feature-flagged). Overrides accept one or two characters, so 'u' and 'us' are both valid.

Letting the fallback do the work. On panels with many items the package derives two-letter chords from the label (g c u for “Customers”) before falling back to digits. Resist pinning everything: pin only the handful of destinations people hit daily, and let the derivation handle the long tail. This keeps the chord space stable as you add resources.

Grouping for the sheet. Because sheet rows are grouped by navigation group and sections flow into balanced columns, navigationGroups() ordering on the panel is now a UX decision, not just a sidebar one. Put high-traffic groups first.

Disabling hints selectively. ->navigationHints(false) is panel-scoped. Use it on panels where the badges would compete with dense custom sidebar rendering, while leaving the chord pill and sheet active — the two features are independent.

Search-in-sidebar panels. If the panel uses ->topbar(false) or GlobalSearchPosition::Sidebar, the shortcuts button renders inside the global search field, falling back to the topbar end or the sidebar footer. No extra configuration is needed, but check the rendered position on each panel layout you ship.

Testing your integration. The package ships JS unit tests and a Playwright suite against a Testbench workbench. Mirror that in CI (npm test, npm run test:e2e) if you customise chords or add resources whose derived shortcuts you care about — a chord collision is exactly the kind of thing a browser test catches and a PHP test does not.

Gotchas and Tips

• Upgrade if Filament bindings went dead. Prior to v0.2.0 the closed sheet carried aria-modal="true", which made Filament believe a modal was open and silently disabled global search and every ->keyBindings() action. If users reported “shortcuts stopped working after installing this”, this is the cause. The attribute is now only set while the sheet is open.
• Ambiguous prefixes need Enter. Typing a prefix that matches multiple items does not auto-select. The chord pill shows the keys typed so far plus a “then a letter” hint — treat Enter as the confirm key when documenting shortcuts for your team.
• Esc is now immediate. It hides the pill straight away rather than waiting; don’t build onboarding copy that assumes a delay.
• Search semantics changed. Combos are matched by key, so shift+x or g+c no longer match labels that merely contain those letters. If you documented “search for the shortcut” as a discovery trick, the behaviour is narrower and more predictable now.
• Two-letter overrides are accepted, but keep them meaningful. g + a single letter is fastest; two-letter chords exist mainly to disambiguate large panels. Avoid pinning a two-letter chord that collides with a derived prefix.
• O vs 0 is intentional. Letter keys and badges use the panel font so they stay distinguishable. Don’t override badge typography with a monospace stack or you lose that.
• Accessibility surface is real. Sidebar links expose the chord as aria-description (and as title when Filament shows no tooltip). If you add custom tooltips, check you aren’t duplicating the chord announcement twice.
• RTL, dark mode, and reduced motion are handled. Hints fade only under prefers-reduced-motion; the active table row uses a direction-agnostic focus ring instead of an inline-start bar. Don’t re-add positional styling that assumes LTR.
• Translations are broad but must stay in sync. Locales cover English, French, Arabic, Chinese (Simplified/Traditional), Czech, Dutch, German, Hebrew, Hindi, Indonesian, Italian, Japanese, Korean, Persian, Polish, Portuguese (PT/BR), Russian, Spanish, Turkish, Ukrainian, and Vietnamese, with terms aligned to Filament’s own translations and key labels matched to each locale’s keyboard. A test keeps every locale in step with English — if you add strings, add the locale entries or that test will fail.
• Sheet layout is stable by design. Sections flow into balanced columns, the dialog keeps its height while filtering, and the empty state suggests what to search. If you inject custom content into the sheet, preserve the fixed height or filtering will cause layout jumps.