EventIntermediateBrowser APIshooks/events/useKeyPress.ts

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 · useKeyPress
Editor
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.ts for implementation details