useKeyboardShortcut — Register keyboard shortcuts with modifier key support

import { useEffect, useRef, useCallback } from "react";
 
interface ShortcutOptions {
  /** Require Ctrl (or Cmd on Mac). Default: false */
  ctrl?: boolean;
  /** Require Shift. Default: false */
  shift?: boolean;
  /** Require Alt (Option on Mac). Default: false */
  alt?: boolean;
  /** Require Meta (Cmd on Mac, Win on Windows). Default: false */
  meta?: boolean;
  /** Call event.preventDefault(). Default: true */
  preventDefault?: boolean;
  /** Only fire when this is true. Default: true */
  enabled?: boolean;
  /** Target element. Default: document */
  target?: EventTarget | null;
}
 
function useKeyboardShortcut(
  key: string,
  callback: (event: KeyboardEvent) => void,
  options: ShortcutOptions = {}
): void {
  const {
    ctrl = false,
    shift = false,
    alt = false,
    meta = false,
    preventDefault = true,
    enabled = true,
    target,
  } = options;
 
  const callbackRef = useRef(callback);
 
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);
 
  useEffect(() => {
    if (!enabled) return;
 
    const eventTarget = target ?? document;
 
    const handler = (e: Event) => {
      const event = e as KeyboardEvent;
 
      // Normalize the key comparison (case-insensitive)
      if (event.key.toLowerCase() !== key.toLowerCase()) return;
 
      // Check modifier keys
      // Use metaKey OR ctrlKey for cross-platform Cmd/Ctrl
      const ctrlMatch = ctrl
        ? event.ctrlKey || event.metaKey
        : !event.ctrlKey && !event.metaKey;
 
      // If ctrl option is set, skip individual meta check
      const metaMatch = ctrl ? true : meta ? event.metaKey : !event.metaKey;
      const shiftMatch = shift ? event.shiftKey : !event.shiftKey;
      const altMatch = alt ? event.altKey : !event.altKey;
 
      if (!ctrlMatch || !shiftMatch || !altMatch || (!ctrl && !metaMatch)) {
        return;
      }
 
      if (preventDefault) {
        event.preventDefault();
      }
 
      callbackRef.current(event);
    };
 
    eventTarget.addEventListener("keydown", handler);
    return () => eventTarget.removeEventListener("keydown", handler);
  }, [key, ctrl, shift, alt, meta, preventDefault, enabled, target]);
}
 
/**
 * useKeyboardShortcuts
 * Register multiple shortcuts at once.
 */
function useKeyboardShortcuts(
  shortcuts: Array<{
    key: string;
    callback: (event: KeyboardEvent) => void;
    options?: ShortcutOptions;
  }>
): void {
  const shortcutsRef = useRef(shortcuts);
 
  useEffect(() => {
    shortcutsRef.current = shortcuts;
  }, [shortcuts]);
 
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      for (const shortcut of shortcutsRef.current) {
        const opts = shortcut.options ?? {};
        const {
          ctrl = false,
          shift = false,
          alt = false,
          meta = false,
          preventDefault = true,
          enabled = true,
        } = opts;
 
        if (!enabled) continue;
        if (e.key.toLowerCase() !== shortcut.key.toLowerCase()) continue;
 
        const ctrlMatch = ctrl
          ? e.ctrlKey || e.metaKey
          : !e.ctrlKey && !e.metaKey;
        const metaMatch = ctrl ? true : meta ? e.metaKey : !e.metaKey;
        const shiftMatch = shift ? e.shiftKey : !e.shiftKey;
        const altMatch = alt ? e.altKey : !e.altKey;
 
        if (!ctrlMatch || !shiftMatch || !altMatch || (!ctrl && !metaMatch)) {
          continue;
        }
 
        if (preventDefault) e.preventDefault();
        shortcut.callback(e);
        break; // Only fire the first matching shortcut
      }
    };
 
    document.addEventListener("keydown", handler);
    return () => document.removeEventListener("keydown", handler);
  }, []);
}

"use client";
 
import { useState } from "react";
 
function CommandPalette() {
  const [isOpen, setIsOpen] = useState(false);
  const [query, setQuery] = useState("");
 
  // Ctrl+K or Cmd+K opens the palette
  useKeyboardShortcut("k", () => setIsOpen(true), { ctrl: true });
 
  // Escape closes it
  useKeyboardShortcut("Escape", () => setIsOpen(false), {
    enabled: isOpen,
    preventDefault: false,
  });
 
  if (!isOpen) return null;
 
  return (
    <div
      style={{
        position: "fixed",
        inset: 0,
        background: "rgba(0,0,0,0.5)",
        display: "flex",
        alignItems: "flex-start",
        justifyContent: "center",
        paddingTop: 100,
        zIndex: 1000,
      }}
    >
      <div
        style={{
          background: "#fff",
          borderRadius: 12,
          padding: 16,
          width: 500,
          maxWidth: "90vw",
          boxShadow: "0 16px 48px rgba(0,0,0,0.2)",
        }}
      >
        <input
          autoFocus
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="Type a command..."
          style={{
            width: "100%",
            padding: 12,
            fontSize: 16,
            border: "1px solid #e0e0e0",
            borderRadius: 8,
            outline: "none",
          }}
        />
        <div style={{ marginTop: 8, color: "#666", fontSize: 14 }}>
          Press Escape to close
        </div>
      </div>
    </div>
  );
}
 
function EditorWithShortcuts() {
  const [content, setContent] = useState("Hello, world!");
  const [saved, setSaved] = useState(false);
 
  // Ctrl+S to save
  useKeyboardShortcut("s", () => {
    console.log("Saving:", content);
    setSaved(true);
    setTimeout(() => setSaved(false), 2000);
  }, { ctrl: true });
 
  // Ctrl+Shift+Z to redo
  useKeyboardShortcut("z", () => {
    console.log("Redo");
  }, { ctrl: true, shift: true });
 
  return (
    <div>
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        style={{ width: "100%", height: 200 }}
      />
      {saved && <span style={{ color: "green" }}>Saved!</span>}
    </div>
  );
}

function useKeySequence(keys: string[], callback: () => void, timeout = 1000) {
  const indexRef = useRef(0);
  const timerRef = useRef<ReturnType<typeof setTimeout>>();
 
  useEffect(() => {
    const handler = (e: KeyboardEvent) => {
      if (e.key.toLowerCase() === keys[indexRef.current].toLowerCase()) {
        indexRef.current++;
        clearTimeout(timerRef.current);
 
        if (indexRef.current === keys.length) {
          callback();
          indexRef.current = 0;
        } else {
          timerRef.current = setTimeout(() => {
            indexRef.current = 0;
          }, timeout);
        }
      } else {
        indexRef.current = 0;
      }
    };
 
    document.addEventListener("keydown", handler);
    return () => document.removeEventListener("keydown", handler);
  }, [keys, callback, timeout]);
}

const inputRef = useRef<HTMLInputElement>(null);
useKeyboardShortcut("Enter", handleSubmit, {
  target: inputRef.current,
  preventDefault: false,
});