useKeyPress
Handle a key or key filter.
Import
TypeScript
import { useKeyPress } from '@/hooks';API
Signature
useKeyPress(filter, handler, options?)
When to use
Use useKeyPress instead of re-implementing the same pattern in multiple components.
SSR / Next.js
No-ops until document/window exist.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · useKeyPressEditor
function Shortcuts() { useKeyPress('s', () => console.log('save'), { preventDefault: true }); return <p>Press S</p>; }
Preview
Implementation source
Full library source for useKeyPress — copy into your project when you are not installing a package yet.
hooks/events/useKeyPress.ts
import { useEffect } from 'react';
import { isBrowser } from '../utility/isBrowser';
import { useLatest } from '../utility/useLatest';
export type KeyFilter = string | string[] | ((event: KeyboardEvent) => boolean);
function matchKey(filter: KeyFilter, event: KeyboardEvent): boolean {
if (typeof filter === 'function') return filter(event);
if (Array.isArray(filter)) {
return filter.some((k) => k === event.key || k === event.code);
}
return filter === event.key || filter === event.code;
}
/** Calls handler when a matching key is pressed. */
export function useKeyPress(
keyFilter: KeyFilter,
handler: (event: KeyboardEvent) => void,
options: {
event?: 'keydown' | 'keyup' | 'keypress';
target?: EventTarget | null;
enabled?: boolean;
preventDefault?: boolean;
} = {},
): void {
const {
event = 'keydown',
target,
enabled = true,
preventDefault = false,
} = options;
const handlerRef = useLatest(handler);
const filterRef = useLatest(keyFilter);
useEffect(() => {
if (!isBrowser() || !enabled) return;
const el = target ?? window;
const listener = (e: Event) => {
const ke = e as KeyboardEvent;
if (!matchKey(filterRef.current, ke)) return;
if (preventDefault) ke.preventDefault();
handlerRef.current(ke);
};
el.addEventListener(event, listener);
return () => el.removeEventListener(event, listener);
}, [event, target, enabled, preventDefault, handlerRef, filterRef]);
}
Copy-paste example
useKeyPress.example.tsx
'use client';
import { useKeyPress } from '@/hooks';
export function Shortcuts() {
useKeyPress('s', () => console.log('save'), { preventDefault: true });
return <p>Press S</p>;
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Pass all relevant refs to useClickOutside (trigger + panel). Prefer useLatest for handlers.
- Source of truth: open
hooks/events/useKeyPress.tsfor implementation details