use-keypress (use-keypress)

Tracks the user's keyboard combinations and key presses.

v0.1.0

Usage

import { use-keypress } from "@/hooks"

"use client";

import React from "react";

import confetti from "canvas-confetti";

import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

import { useKeypress } from "@/components/hooks/use-keypress";

export function UseKeypressDemo() {
  const popStars = () => {
    const defaults = {
      spread: 360,
      ticks: 50,
      gravity: 0,
      decay: 0.94,
      startVelocity: 30,
      colors: ["#FFE400", "#FFBD00", "#E89400", "#FFCA6C", "#FDFFB8"],
    };

    const shoot = () => {
      confetti({
        ...defaults,
        particleCount: 40,
        scalar: 1.2,
        shapes: ["star"],
      });

      confetti({
        ...defaults,
        particleCount: 10,
        scalar: 0.75,
        shapes: ["circle"],
      });
    };

    setTimeout(shoot, 0);
    setTimeout(shoot, 100);
    setTimeout(shoot, 200);
  };

  useKeypress({
    combo: ["ctrl+m", "meta+m"],
    callback: (e) => {
      popStars();
    },
    preventDefault: true,
  });

  return (
    <Card className="relative max-w-sm w-full">
      <CardHeader>
        <CardTitle>useKeypress</CardTitle>
        <CardDescription>
          This component uses the <code>useKeypress</code> hook to detect key
          combinations.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-2">
        <p>Press Ctrl+M (Windows/Linux) or Cmd+M (Mac) to see some magic.</p>
      </CardContent>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-keypress

Options

Name	Type	Default	Description
combo	string	null	The combination of keys to listen for
callback	function	null	The callback to be called when the key or combination is pressed
preventDefault	boolean	false	If true, the event will be prevented from propagating
target	HTMLElement	null	The target element to listen for the key or combination

Combo Normalization & Modifiers

The combo string is case-insensitive and order-insensitive for modifiers.
Supported modifiers: ctrl , alt , shift , meta (for Command on Mac, Windows key on Windows).
Example: "Ctrl+Shift+S" , "shift+ctrl+s" , and "CTRL+s+SHIFT" are all equivalent.
Only one non-modifier key is supported per combo (e.g., "ctrl+s" is valid, "ctrl+s+d" is not).

Multiple Combos

The combo prop can be a string or an array of strings. If an array, the callback fires for any matching combo.
Example: combo: ['ctrl+s', 'meta+s'] will trigger for either combination.

Target Element

By default, the hook listens on window , but you can specify a target HTMLElement (e.g., an input or div).
For best performance, use a stable reference (e.g., from useRef ) for the target. Changing the target frequently will cause listeners to be re-attached.

Performance Notes

The hook memoizes normalized combos and the event handler for efficiency.
Listeners are automatically cleaned up when the component unmounts or the target changes.

Event Handling

The hook listens for the keydown event.
If preventDefault is true, the default browser action is prevented for the matching combo.
The callback receives the original KeyboardEvent .

Caveats & Best Practices

Only one non-modifier key is supported per combo.
Modifier order does not matter, but all specified modifiers must be pressed.
The hook is designed for keyboard shortcuts, not for general key tracking (e.g., holding multiple non-modifier keys).

Files in this hook

Source	Destination
files/use-keypress.ts	src/hooks/use-keypress.ts