| name | studio-shortcuts |
| description | Keyboard shortcut conventions for Supabase Studio. Use when adding a repeated user action, toolbar action, list/table operation, or sub-page navigation that should have shortcut coverage, when registering or changing a shortcut, or when adding a search/filter Input (which needs the staged-Escape handler). Covers the shortcut registry, useShortcut, ShortcutTooltip/ShortcutBadge, the reference sheet, and collision rules. |
Studio Keyboard Shortcuts
When Studio UI changes introduce or materially alter repeated user actions, consider whether keyboard shortcut coverage should be added or updated. Shortcuts use the shared Studio shortcut system and must be discoverable from the visible UI.
Rules
- Never add a one-off
keydown listener for a normal Studio action — register it through the shortcut registry and useShortcut.
- Every registered shortcut is exposed where the action is visible, via
ShortcutTooltip, ShortcutBadge, or a command-menu badge.
G then … chords are reserved for navigation.- Avoid broad
Mod+letter shortcuts that overlap common browser, editor, system, copy/save/search, or devtools behavior.
- Before adding a shortcut, check the registry and any remaining non-registry listeners for collisions.
- Every search/filter
<Input> gets onKeyDown={onSearchInputEscape(...)} — see Search inputs.
Preferred pattern
- Add definitions in
apps/studio/state/shortcuts/registry.ts or apps/studio/state/shortcuts/registry/*.
- Register with
useShortcut.
- Gate availability with
enabled.
- Surface visible actions with
ShortcutTooltip or ShortcutBadge.
- Prefer scoped, mnemonic sequential chords over global modifier chords.
- Set
showInSettings: false on contextual shortcuts (scoped to a specific page state, sheet, or panel).
- When a shortcut group should appear in the reference sheet (
Shift+?), add the group key to SHORTCUT_REFERENCE_GROUP_ORDER in apps/studio/state/shortcuts/referenceGroups.ts and a human label to GROUP_LABELS in ShortcutsReferenceSheet.tsx.
- For sheet-scoped shortcuts (active only while a
<Sheet> is open), mount useShortcut inside the sheet component gated by the open prop ({ enabled: open }) — apps/studio/components/interfaces/Platform/Webhooks/PlatformWebhooksDeliveryDetailsSheet.tsx is the canonical example. A shortcut that opens a sheet from anywhere is global instead, gated by whatever makes the action valid (e.g. useConnectSheetShortcut checks project health).
Search inputs
Every <Input> used as a search or filter field must include the staged-Escape handler from apps/studio/lib/keyboard.ts:
import { onSearchInputEscape } from '@/lib/keyboard'
;<Input
value={query}
onChange={(e) => setQuery(e.target.value)}
onKeyDown={onSearchInputEscape(query, setQuery)}
/>
Behavior:
- Escape while the input has a value → clears the value, keeps focus (so a second Escape then blurs)
- Escape while the input is empty → blurs the input
- Stops propagation on Escape so the keystroke does not accidentally close a parent dialog or sheet
When pairing with useShortcut(LIST_PAGE_FOCUS_SEARCH, ...) to focus a search input via keyboard, always also add onSearchInputEscape on the same input — focus and escape-to-blur are always a pair.
Key files
apps/studio/state/shortcuts/registry.ts, apps/studio/state/shortcuts/useShortcut.tsx, apps/studio/components/ui/Shortcut*.tsx, apps/studio/lib/keyboard.ts.
Tests
E2E tests for a feature with shortcuts cover both click interactions and the keyboard path — see studio-e2e-tests.
