Sensors

useOnKeyStroke

Listen for keyboard key strokes with optional key filtering. Supports string keys, arrays of keys, predicate functions, or true to match all keys.

Usage

Hook
Scope

import { 
const useOnKeyStroke: {
    (key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn;
    (handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn;
}
useOnKeyStroke, 
function useOnKeyDown(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn
Listen for keydown events with key filtering.
useOnKeyDown, 
function useOnKeyUp(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn
Listen for keyup events with key filtering.
useOnKeyUp } from "@usels/web";

function 
function KeyStrokeDemo(): JSX.Element
KeyStrokeDemo() {
  // Single key
  
function useOnKeyStroke(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn (+1 overload)
Framework-agnostic keyboard key stroke listener with key filtering.
@param ― key - Key filter (string, string[], predicate, or true for all)
@param ― handler - Callback fired when a matching key event occurs
@param ― options - Configuration options
@returns ― A stop function that removes the event listener
useOnKeyStroke("Enter", (
e: KeyboardEvent
e) => {
    
any
console.
any
log("Enter pressed!");
  });

  // Multiple keys
  
function useOnKeyStroke(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn (+1 overload)
Framework-agnostic keyboard key stroke listener with key filtering.
@param ― key - Key filter (string, string[], predicate, or true for all)
@param ― handler - Callback fired when a matching key event occurs
@param ― options - Configuration options
@returns ― A stop function that removes the event listener
useOnKeyStroke(["ArrowUp", "ArrowDown"], (
e: KeyboardEvent
e) => {
    
any
console.
any
log(`Arrow ${
e: KeyboardEvent
e.
any
key} pressed!`);
  });

  // Predicate function
  
function useOnKeyStroke(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn (+1 overload)
Framework-agnostic keyboard key stroke listener with key filtering.
@param ― key - Key filter (string, string[], predicate, or true for all)
@param ― handler - Callback fired when a matching key event occurs
@param ― options - Configuration options
@returns ― A stop function that removes the event listener
useOnKeyStroke((
e: KeyboardEvent
e) => 
e: KeyboardEvent
e.
any
key === "a" && 
e: KeyboardEvent
e.
any
ctrlKey, (
e: KeyboardEvent
e) => {
    
any
console.
any
log("Ctrl+A pressed!");
  });

  // All keys (handler-only overload)
  
function useOnKeyStroke(handler: (event: KeyboardEvent) => void, options?: DeepMaybeObservable<UseOnKeyStrokeOptions>): UseOnKeyStrokeReturn (+1 overload)
Framework-agnostic keyboard key stroke listener for all keys.
@param ― handler - Callback fired on every key event
@param ― options - Configuration options
@returns ― A stop function that removes the event listener
useOnKeyStroke((
e: KeyboardEvent
e) => {
    
any
console.
any
log(`Key: ${
e: KeyboardEvent
e.
any
key}`);
  });

  // Convenience hooks for specific event types
  
function useOnKeyDown(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn
Listen for keydown events with key filtering.
useOnKeyDown("Escape", (
e: KeyboardEvent
e) => 
any
console.
any
log("Escape down"));
  
function useOnKeyUp(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn
Listen for keyup events with key filtering.
useOnKeyUp("Escape", (
e: KeyboardEvent
e) => 
any
console.
any
log("Escape up"));

  return <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>Press any key</
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>;
}

import { createOnKeyStroke, createOnKeyDown, createOnKeyUp } from "@usels/web";

function KeyStrokeDemo() {
  "use scope";

  // Single key
  createOnKeyStroke("Enter", (e) => {
    console.log("Enter pressed!");
  });

  // Multiple keys
  createOnKeyStroke(["ArrowUp", "ArrowDown"], (e) => {
    console.log(`Arrow ${e.key} pressed!`);
  });

  // Predicate function
  createOnKeyStroke((e) => e.key === "a" && e.ctrlKey, (e) => {
    console.log("Ctrl+A pressed!");
  });

  // All keys (handler-only overload)
  createOnKeyStroke((e) => {
    console.log(`Key: ${e.key}`);
  });

  // Convenience functions for specific event types
  createOnKeyDown("Escape", (e) => console.log("Escape down"));
  createOnKeyUp("Escape", (e) => console.log("Escape up"));

  return <div>Press any key</div>;
}

Options

useOnKeyStroke("Enter", handler, {
  eventName: "keyup", // "keydown" | "keypress" | "keyup" — default: "keydown"
  dedupe: true, // ignore repeat events when key is held down
  passive: true, // use passive event listener
  target: myElement, // custom event target — default: window
});

Type

export { createOnKeyStroke, createOnKeyDown, createOnKeyPressed, createOnKeyUp } from "./core";
export type { KeyPredicate, KeyFilter, KeyStrokeEventName, UseOnKeyStrokeOptions, UseOnKeyStrokeReturn, } from "./core";
export type UseOnKeyStroke = typeof createOnKeyStroke;
export declare const useOnKeyStroke: UseOnKeyStroke;
/**
 * Listen for `keydown` events with key filtering.
 */
export declare function useOnKeyDown(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn;
/**
 * Listen for `keypress` events with key filtering.
 */
export declare function useOnKeyPressed(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn;
/**
 * Listen for `keyup` events with key filtering.
 */
export declare function useOnKeyUp(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseOnKeyStrokeOptions, "eventName">): Fn;

Source

View on GitHub