useHotKeys

Hook to listen for the keyboard press, support key combinations, built on hotKeyHandler utility function.

Demo

INFO

The component uses useHotKeys hook to print a message on ctrl+shift+a, ctrlCommand+p and ctrlCommand+a keys combinations and clear message when Escape is pressed.

Loading demo…

Show source code

import { useState } from "react";
import { useHotKeys } from "../../../.."

export const UseHotKeys = () => {
	const [state, setState] = useState("");
	useHotKeys({
		hotKey: "ctrl+shift+b",
		listener: (evt) => {
			evt.preventDefault();
			setState("ctrl+shift+b")
		}
	});
	useHotKeys({
		hotKey: "ctrlCommand++",
		listener: (evt) => {
			evt.preventDefault();
			setState("ctrlCommand++")
		}
	});
	useHotKeys({
		hotKey: "ctrlCommand+a",
		listener: (evt) => {
			evt.preventDefault();
			setState("ctrlCommand+a")
		}
	});
	useHotKeys({
		hotKey: "Escape",
		listener: (evt) => {
			evt.preventDefault();
			setState("")
		}
	});

	return <>
		<p>Message: {state ? <><strong style={{color: "darkcyan"}}>{state}</strong> pressed.</>: ""}</p>
	</>
}

Types

UseHotKeysProps

Parameters accepted by useHotKeys.

Property	Type	Required	Description
hotKey	\| '${string}' \| '${"alt" \| "ctrl" \| "meta" \| "shift" \| "ctrlCommand"}+${string}' \| '${"alt" \| "ctrl" \| "meta" \| "shift" \| "ctrlCommand"}+${"alt" \| "ctrl" \| "meta" \| "shift" \| "ctrlCommand"}+${string}'	✓	The keyboard shortcut string to listen for. Supports the following formats: - A bare key string (e.g. "s", "Enter"). - A single modifier combined with a key using + (e.g. "ctrl+s"). - Two modifiers combined with a key using + (e.g. "ctrl+shift+z"). Supported modifiers: "alt", "ctrl", "meta", "shift", "ctrlCommand" (maps to ctrl on Windows/Linux and meta on macOS).
type	"keydown" \| "keyup"		The keyboard event type to listen for. - "keydown" (default) — Fires when the key is pressed. - "keyup" — Fires when the key is released.
target	RefObject<HTMLElement> \| Window		The target on which the keyboard event listener is registered. Accepts either a React RefObject&lt;HTMLElement&gt; or a direct Window reference. Defaults to window when omitted.
listener	(evt: KeyboardEvent \| KeyEvt<HTMLElement>) => void \| Promise<void>	✓	Callback invoked when the configured hotkey combination is detected. Receives the native {@link KeyboardEvent} or a {@link KeyEvt} for element-scoped targets. May return a Promise for async handlers.
listenerOpts	boolean \| AddEventListenerOptions		Options forwarded to addEventListener as the third argument. Accepts either a boolean shorthand for capture or a full {@link AddEventListenerOptions} object. When omitted, the listener is registered with the browser defaults.

UseHotKeysResult

Return value of useHotKeys.

A stable cleanup function that manually removes the keyboard event listener from the target. Calling it is optional — the hook cleans up automatically on unmount — but useful to detach the listener earlier on demand.

export type UseHotKeysResult = () => void;