useShortcutRecorder

A React hook for effortlessly capturing and validating keyboard shortcut keys.

• Record keyboard shortcuts with modifier keys (Ctrl, Alt, Shift, Meta/Command)
• Customizable validation rules:
  • Min/max number of modifier keys
  • Excluded keys and modifiers
  • Excluded shortcut combinations

Demo

https://stackblitz.com/edit/react-brtovrsp?file=Shortcut.jsx

Installation

npm install use-shortcut-recorder

Usage

import { useShortcutRecorder } from 'use-shortcut-recorder';


function ShortcutInput() {

  const {
    shortcut,
    savedShortcut,
    isRecording,
    error,
    startRecording,
    stopRecording,
    resetRecording,
    clearLastRecording,
  } = useShortcutRecorder({
    onChange: (newShortcut) => {
      console.log('Shortcut changed:', newShortcut);
    },
    excludedKeys: ['KeyA', 'KeyB'], 
    excludedShortcuts: [
        ['Alt', 'KeyM'],
        ['Meta', 'KeyZ']
    ],
    excludedModKeys: ['Control'],
    maxModKeys: 3,
    minModKeys: 1,
  } );

  return (
    <div>
      <label htmlFor="shortcut-input">Enter Shortcut:</label>

      <input
        id="shortcut-input"
        type="text"
        className='shortcut-input'
        placeholder={
          isRecording ? 'Key Recording Started..' : 'Click to Record Shortcut..'
        }
        onFocus={startRecording}
        onClick={startRecording}
        onBlur={() => stopRecording()}
        value={isRecording 
          ? shortcut.join(' + ') 
          : savedShortcut.join(' + ')}
        readOnly={true}
      />

      {error && <div>{error.message}</div>}

      {savedShortcut && (
        <div>
          Saved Shortcut: <strong>{savedShortcut.join(' + ')}</strong>
        </div>
      )}
       <button onClick={clearLastRecording}>Reset</button>
    </div>
  );
}

API Reference

Hook Options

The useShortcutRecorder hook accepts a configuration object with the following properties:

| Option | Type | Default | Description | |--------|------|---------|-------------| | onChange | (keys: string[]) => void | () => {} | Callback function called when a valid shortcut is recorded | | excludedShortcuts | string[][] | [[]] | Array of shortcut combinations to exclude | | excludedModKeys | string[] | [] | Array of modifier keys to exclude | | excludedKeys | string[] | [] | Array of non-modifier keys to exclude | | minModKeys | number | 0 | Minimum number of modifier keys required | | maxModKeys | number | 4 | Maximum number of modifier keys allowed |

Return Values

The hook returns an object with the following properties:

| Property | Type | Description | |----------|------|-------------| | shortcut | string[] | Current shortcut being recorded | | savedShortcut | string[] | Last successfully recorded shortcut | | isRecording | boolean | Whether the recorder is currently active | | error | ShortcutRecorderError | Current error state | | startRecording | () => void | Function to start recording | | stopRecording | () => void | Function to stop recording | | resetRecording | () => void | Function to reset current recording | | clearLastRecording | () => void | Function to clear saved shortcut |

Error Codes

The error object contains a code and message. Possible error codes:

| Error Code | Description | |------------|-------------| | NONE | No error | | MAX_MOD_KEYS_EXCEEDED | Too many modifier keys used | | MIN_MOD_KEYS_REQUIRED | Not enough modifier keys used | | MOD_KEY_NOT_ALLOWED | Modifier key is in the excluded list | | KEY_NOT_ALLOWED | Non-modifier key is in the excluded list | | SHORTCUT_NOT_ALLOWED | Shortcut combination is in the excluded list |

Keyboard Code Reference

This hook uses keyboard event codes for key identification. For consistency and cross-browser compatibility, all left/right variations of modifier keys (e.g., ShiftLeft/ShiftRight, ControlLeft/ControlRight) are normalized to their base name (e.g., Shift, Control). Specifically, both MetaLeft/MetaRight and the now-deprecated OSLeft/OSRight are mapped to Meta for the Windows/Command key.

License

MIT