The count is {count}.
) } function SecondUnscopedHotkey() { const [count, setCount] = useState(0) useHotkeys('c', () => setCount(prevCount => prevCount + 1)) return (The count is {count}.
) } render(Is recording: {isRecording ? 'yes' : 'no'}
Recorded keys: {Array.from(keys).join(' + ')}
Pressed {count} times.
) } ``` -------------------------------- ### Optional Chaining Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Demonstrates the use of optional chaining (`?.`) to safely access nested properties that might be null or undefined. ```javascript e.target?.isContentEditable ``` -------------------------------- ### Listen to Produced Character '?' Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/ignore-layouts.mdx This example uses `useKey: true` to listen for the produced character '?'. This is useful when the character itself is important, regardless of the physical keys pressed. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) useHotkeys('?', () => setCount(prevCount => prevCount + 1), { useKey: true }) return ( Pressed '?' {count} times. ) } ``` -------------------------------- ### Stale State Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/setting-callback-dependencies.mdx This example demonstrates the stale state problem where a hotkey callback references a state variable directly, leading to outdated values being used after the first update. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) const ref = useHotkeys('b', () => setCount(count + 1)) return ( Pressed the 'b' key {count} times. ) } ``` -------------------------------- ### Listen to Produced Character '!' Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/ignore-layouts.mdx This example uses the `useKey: true` option to listen for the produced character '!' regardless of the physical keys pressed. This approach is layout-dependent. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) useHotkeys('!', () => setCount(prevCount => prevCount + 1), { useKey: true }) return ( Pressed the '!' key {count} times. ) } ``` -------------------------------- ### TODO Comment Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Example of a TODO comment used to mark future improvements or areas for refactoring. ```javascript // TODO: Make modifiers work with sequences ``` -------------------------------- ### Listen to '+' Character with Custom Split Key Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/ignore-layouts.mdx This example demonstrates how to listen for the '+' character when it's used as a hotkey by changing the `splitKey` option to '-' to avoid conflicts with the default '+' split key. ```js // Listen to the '+' character by changing the splitKey useHotkeys('ctrl-+', addItem, { splitKey: '-' }) ``` -------------------------------- ### Listen to Physical Key ';' Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/ignore-layouts.mdx This example shows how to listen to the physical key code 'Semicolon' to trigger a hotkey, ensuring layout independence. The code name is case-insensitive. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) useHotkeys('Semicolon', () => setCount(prevCount => prevCount + 1)) return ( Pressed the ';' key {count} times. ) } ``` -------------------------------- ### Type-Only Import Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Demonstrates the use of `import type` for importing types only, which does not affect the JavaScript output. ```typescript import type { Hotkey } from './types' ``` -------------------------------- ### Basic Usage of useHotkeys Hook Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/intro.mdx Use the useHotkeys hook to bind a keyboard shortcut ('a') to a callback function that increments a counter. This example demonstrates a simple counter that updates when the 'a' key is pressed. ```jsx function MyComponent() { const [count, setCount] = useState(0); useHotkeys('a', () => setCount(count => count + 1)); return ( Pressed the 'a' key {count} times. ); } ``` -------------------------------- ### Biome Ignore Comment Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Demonstrates how to use a `biome-ignore` comment to bypass specific linting rules for a line of code. ```javascript // biome-ignore lint/correctness/useExhaustiveDependencies ``` -------------------------------- ### Type Guard Example Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Illustrates the use of a type guard function to narrow down the type of a variable within a conditional block. ```typescript isReadonlyArray(enabledOnTags) ``` -------------------------------- ### Create Custom Hooks for Editor Shortcuts Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/advanced-usage.mdx Encapsulate related hotkeys within a custom hook to maintain clean components and enforce consistent behavior. This example defines editor-specific shortcuts. ```tsx function useEditorShortcuts() { const { enableScope, disableScope } = useHotkeysContext(); useHotkeys('ctrl+s', saveDocument, { scopes: 'editor', preventDefault: true, description: 'Save document', }); useHotkeys('ctrl+z', undo, { scopes: 'editor', preventDefault: true, description: 'Undo', }); useHotkeys('ctrl+shift+z', redo, { scopes: 'editor', preventDefault: true, description: 'Redo', }); return { enableScope, disableScope }; } function Editor() { useEditorShortcuts(); returnThe count is: {count}
Hold Shift while clicking to decrease.
Recording (ignoring Tab and Enter): {isRecording ? 'yes' : 'no'}
Recorded keys: {Array.from(keys).join(' + ')}
Press cmd+s (or ctrl+s on non-Mac) to open the custom save dialog.
Pressed {count} times.
) } ``` -------------------------------- ### useHotkeys(keys, callback) Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/README.md The useHotkeys hook allows you to easily define keyboard shortcuts within your React components. It accepts a keys configuration, a callback function to execute when the keys are pressed, and optional configuration options. ```APIDOC ## useHotkeys(keys, callback) ### Description This hook registers keyboard shortcuts within a React component. It listens for specified key combinations and executes a provided callback function when those combinations are detected. ### Method `useHotkeys` (Hook) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters #### `keys` - **Type**: `string` or `string[]` - **Required**: Yes - **Description**: Defines the hotkeys to listen for. Can be a single key, multiple keys separated by commas, or an array of key strings. Modifier combinations are supported. #### `callback` - **Type**: `(event: KeyboardEvent, handler: HotkeysEvent) => void` - **Required**: Yes - **Description**: The function to be executed when the specified hotkeys are pressed. It receives the native `KeyboardEvent` and a `HotkeysEvent` object. #### `options` - **Type**: `Options` - **Required**: No - **Default value**: `{}` - **Description**: An object to customize the hook's behavior. Refer to the library's documentation for available options. #### `deps` - **Type**: `DependencyList` - **Required**: No - **Default value**: `[]` - **Description**: An array of dependencies, similar to React's `useEffect` hook, to control when the hotkey listener should re-register. ### Request Example ```javascript useHotkeys('ctrl+s, meta+s', (event, handler) => { // Handle save action console.log('Save shortcut pressed!'); }, [saveAction]); ``` ### Response This hook does not return a value directly, but triggers the callback function when hotkeys are pressed. ``` -------------------------------- ### Using Dependency Array with useHotkeys Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/setting-callback-dependencies.mdx Provide a dependency array to useHotkeys to ensure the callback uses the latest values of external references like memoized values, props, or state. This prevents stale state issues when the callback relies on values that change over time. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) const squaredCount = useMemo(() => count * 2, [count]) const ref = useHotkeys('b', () => setCount(squaredCount + 1), [squaredCount]) return ( Pressed the 'b' key {squaredCount} times. ) } ``` -------------------------------- ### Run Specific Test File Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Executes all tests contained within a specific test file. ```bash npx vitest run src/test/useHotkeys.test.tsx ``` -------------------------------- ### Multiple Key Combinations Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/api/use-hotkeys.mdx Define a single callback for multiple independent key combinations. ```jsx useHotkeys('w, a, s, d', () => alert('Player moved!')) ``` -------------------------------- ### Differentiate Hotkeys with Object Values Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/api/use-hotkeys.mdx Use an object to define hotkeys and their corresponding actions. The `hotkey` property in the handler identifies the matched shortcut. ```jsx const HOTKEYS = { ACTION_A: 'ctrl+a', ACTION_B: 'shift+b', } useHotkeys(Object.values(HOTKEYS), (_, { hotkey }) => { switch (hotkey) { case HOTKEYS.ACTION_A: alert('You pressed ctrl+a!'); break; case HOTKEYS.ACTION_B: alert('You pressed shift+b!'); break; } }) ``` -------------------------------- ### Run Tests in Library Package Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/AGENTS.md Executes tests specifically within the library package. ```bash npm run -w packages/react-hotkeys-hook test ``` -------------------------------- ### Sequential Hotkeys Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/useHotkeys/basic-usage.mdx Listen for keys pressed in sequence using the '>' character. The callback is triggered only after the entire sequence is completed. ```jsx function ExampleComponent() { const [count, setCount] = useState(0) useHotkeys('g>h>i', () => setCount(prevCount => prevCount + 1)) return ( Received the combination {count} times. ) } ``` -------------------------------- ### Recording Produced Characters with useRecordHotkeys Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/use-record-hotkeys.mdx Configures useRecordHotkeys to record the produced characters (e.g., '!') instead of key codes (e.g., 'shift+1') by passing true as the first argument. ```jsx const [keys, controls] = useRecordHotkeys(true); // records characters like "!" instead of "shift+1" ``` -------------------------------- ### Import isHotkeyPressed Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/is-hotkey-pressed.mdx Import the isHotkeyPressed function from the 'react-hotkeys-hook' package before use. ```javascript import { isHotkeyPressed } from 'react-hotkeys-hook'; ``` -------------------------------- ### Type-Safe Key Names with TypeScript Source: https://github.com/johannesklauss/react-hotkeys-hook/blob/main/packages/documentation/docs/documentation/typescript.mdx Demonstrates how TypeScript catches incorrect types for the `keys` argument at compile time. Ensure the `hotKey` prop is a string or array of strings. ```tsx import { useHotkeys } from "react-hotkeys-hook"; import { useState } from "react"; interface Props { hotKey: number; // ❌ wrong type } const MyComponent = ({ hotKey }: Props) => { const [count, setCount] = useState(0); // TypeScript error: hotKey must be a string useHotkeys(hotKey, () => setCount(prevCount => prevCount + 1)); return (