use-keyboard-scope
v1.0.0
Published
Scoped keyboard shortcuts for React: hotkeys that belong to a modal, panel or page and automatically block the ones underneath. Sequences (g i), mod key for Mac/Windows, works with non-Latin keyboard layouts, help-dialog list.
Maintainers
Readme
use-keyboard-scope
Keyboard shortcuts with scopes. When a modal is open, Escape should close the modal — not also the page behind it, and / should not focus the page's search box. Wrap the modal in <HotkeyScope>: hotkeys inside it win, and the page's hotkeys are blocked until it closes.
import { HotkeyScope, useHotkey } from 'use-keyboard-scope';
function Page() {
const [open, setOpen] = useState(false);
useHotkey('mod+k', () => setOpen(true), { description: 'Open command palette' });
useHotkey('/', () => searchRef.current?.focus(), { description: 'Search' });
return (
<HotkeyScope name="palette" active={open}>
{open && <CommandPalette onClose={() => setOpen(false)} />}
</HotkeyScope>
);
}
function CommandPalette({ onClose }: { onClose: () => void }) {
useHotkey('escape', onClose); // only fires while the palette is on top
useHotkey('mod+enter', runSelected);
return <input autoFocus />;
}Install
npm install use-keyboard-scopeFeatures
- Scopes stack: the most recently opened scope is active; nested modals just work. Scopes can let globals through with
blockGlobal={false}. - Syntax:
mod+k(⌘ on Mac, Ctrl on Windows/Linux),ctrl+shift+p,alt+1,escape,?, arrows, sequences likeg i(GitHub style), several at once['mod+s', 'ctrl+s']. - Any keyboard layout: falls back to the physical key, so
mod+kworks on Cyrillic, Arabic, Greek… layouts. - Form-friendly: plain keys are ignored while typing in inputs; combos with Ctrl/⌘/Alt and
Escapestill work (override withenableOnFormFields). - Help dialog:
useHotkeyList()returns the active shortcuts with descriptions and labels (⌘K/Ctrl+K). - One shared
keydownlistener, no matter how many hotkeys.
API
| Export | Description |
| --- | --- |
| useHotkey(keys, handler, options?) | Options: scope, enabled, preventDefault (true), stopPropagation, enableOnFormFields, description |
| <HotkeyScope name active? blockGlobal?> | Scope component; hotkeys inside belong to it |
| useHotkeyScope(name, { active, blockGlobal }) | Hook version |
| useHotkeyList() | { hotkey, label, description, scope }[] currently active |
| useActiveScope() | Name of the top scope or null |
| formatHotkey('mod+shift+p') | ⌘⇧P / Ctrl+Shift+P |
| parseHotkey(text) | Parsed chords |
Shortcut help dialog
function ShortcutHelp() {
const hotkeys = useHotkeyList();
return (
<ul>
{hotkeys.filter((h) => h.description).map((h) => (
<li key={h.hotkey}><kbd>{h.label}</kbd> {h.description}</li>
))}
</ul>
);
}License
MIT
