Function: useHotkey()

function useHotkey(
   hotkey, 
   callback, 
   options): void;

function useHotkey(
   hotkey, 
   callback, 
   options): void;

Defined in: useHotkey.ts:89

React hook for registering a keyboard hotkey.

Uses the singleton HotkeyManager for efficient event handling. The callback receives both the keyboard event and a context object containing the hotkey string and parsed hotkey.

This hook syncs the callback and options on every render to avoid stale closures. This means callbacks that reference React state will always have access to the latest values.

Parameters

hotkey

The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports for cross-platform)

callback

The function to call when the hotkey is pressed

options

Options for the hotkey behavior. keeps the registration (visible in devtools) and only suppresses firing; the hook updates the existing handle instead of unregistering.

Returns

Examples

tsx

function SaveButton() {
  const [count, setCount] = useState(0)

  // Callback always has access to latest count value
  useHotkey('Mod+S', (event, { hotkey }) => {
    console.log(`Save triggered, count is ${count}`)
    handleSave()
  })

  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
}

function SaveButton() {
  const [count, setCount] = useState(0)

  // Callback always has access to latest count value
  useHotkey('Mod+S', (event, { hotkey }) => {
    console.log(`Save triggered, count is ${count}`)
    handleSave()
  })

  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
}

tsx

function Modal({ isOpen, onClose }) {
  // enabled option is synced on every render
  useHotkey('Escape', () => {
    onClose()
  }, { enabled: isOpen })

  if (!isOpen) return null
  return <div className="modal">...</div>
}

function Modal({ isOpen, onClose }) {
  // enabled option is synced on every render
  useHotkey('Escape', () => {
    onClose()
  }, { enabled: isOpen })

  if (!isOpen) return null
  return <div className="modal">...</div>
}

tsx

function Editor() {
  const editorRef = useRef<HTMLDivElement>(null)

  // Scoped to a specific element
  useHotkey('Mod+S', () => {
    save()
  }, { target: editorRef })

  return <div ref={editorRef}>...</div>
}

function Editor() {
  const editorRef = useRef<HTMLDivElement>(null)

  // Scoped to a specific element
  useHotkey('Mod+S', () => {
    save()
  }, { target: editorRef })

  return <div ref={editorRef}>...</div>
}

useHotkey

Function: useHotkey()#

Parameters#

hotkey#

callback#

options#

Returns#