Overview
isHotkeyPressed is a utility function that allows you to check whether a specific key or combination of keys is currently being pressed. This is useful for conditional logic based on the current keyboard state.
This function tracks the global keyboard state and works independently of React components. It can be called anywhere in your application.
Signature
function isHotkeyPressed(
key: string | readonly string[],
delimiter?: string
): boolean
Parameters
key
string | readonly string[]
required
The key or keys to check. Can be a single key string, a comma-separated string of multiple keys, or an array of key strings.Keys are case-insensitive and will be automatically trimmed of whitespace.
The delimiter used to split the key string if provided as a string. Only used when key is a string, not an array.
Returns
Returns true if all specified keys are currently pressed, false otherwise.
Usage
Basic Key Check
import { isHotkeyPressed } from 'react-hotkeys-hook'
function MyComponent() {
const handleClick = () => {
if (isHotkeyPressed('shift')) {
console.log('Shift is currently pressed')
}
}
return <button onClick={handleClick}>Click me</button>
}
Multiple Keys
Check if multiple keys are pressed simultaneously:
import { isHotkeyPressed } from 'react-hotkeys-hook'
function MyComponent() {
const handleAction = () => {
// Check using comma-separated string
if (isHotkeyPressed('ctrl,shift')) {
console.log('Ctrl+Shift is pressed')
}
// Or check using array
if (isHotkeyPressed(['ctrl', 'alt'])) {
console.log('Ctrl+Alt is pressed')
}
}
return <button onClick={handleAction}>Perform action</button>
}
Custom Delimiter
import { isHotkeyPressed } from 'react-hotkeys-hook'
// Use a custom delimiter
if (isHotkeyPressed('ctrl+shift', '+')) {
console.log('Ctrl and Shift are both pressed')
}
Conditional Behavior
Use isHotkeyPressed to modify behavior based on modifier keys:
import { isHotkeyPressed } from 'react-hotkeys-hook'
function FileList() {
const handleFileClick = (file: File) => {
if (isHotkeyPressed('meta') || isHotkeyPressed('ctrl')) {
// Add to selection (multi-select)
addToSelection(file)
} else if (isHotkeyPressed('shift')) {
// Range select
selectRange(file)
} else {
// Single select
selectFile(file)
}
}
return (
<div>
{files.map(file => (
<div key={file.id} onClick={() => handleFileClick(file)}>
{file.name}
</div>
))}
</div>
)
}
Important Notes
The function is case-insensitive. Both isHotkeyPressed('Shift') and isHotkeyPressed('shift') will work identically.
Key names are automatically trimmed of whitespace, so 'ctrl, shift' and 'ctrl,shift' are equivalent.
When checking multiple keys, ALL specified keys must be pressed for the function to return true. It uses an “AND” operation, not an “OR” operation.
How It Works
The library maintains a global set of currently pressed keys by listening to keydown and keyup events on the document. The set is automatically cleared when:
- The window loses focus (
blur event)
- The context menu is opened (macOS meta key behavior)
- The meta key is released (macOS-specific behavior)
This ensures accurate tracking of the keyboard state across different operating systems and edge cases.