UseDetectKeyDown

Last updated: 2.0.0 (22/01/2024)

useDetectKeyDown detects when a key is pressed and fires the callback function. It attaches the event listener to the document body, thus making it handy for keyboard shortcuts, etc.

Usage

import { useDetectKeyDown, Text } from "@valence-ui/core";

function MyComponent() { 
    useDetectKeyDown(
        (e) => console.log("Key pressed!", e),
        "Escape",
        true,
    );
    
    return ( 
        <Text> 
            Press `Escape`!
        </Text>
    )
}

Listen for multiple keys

Passing a list of keycodes into the keys parameter allows the hook to listen for any number of keys. A switch block in the callback function may be necessary to distinguish between the keys pressed.

import { useDetectKeyDown, Text } from "@valence-ui/core";

function MyComponent() { 
    useDetectKeyDown(
        (e) => {
            switch(e.key) {
                case "Escape": return console.log("Escape pressed!");
                case "F": return console.log("F pressed!");
                default: return console.log("Unknown key pressed!");
            }
        },
        ["Escape", "F", "G"],
        true,
    );
    
    return ( 
        <Text> 
            Press `Escape`, "F" or "G"!
        </Text>
    )
}

Controlled listening

Using a Disclosure or boolean state allows you to control when the hook is listening for keyboard events, without unmounting the component it is attached to.

import { useDetectKeyDown, useDisclosure, Button } from "@valence-ui/core";

function MyComponent() {
    const disclosure = useDisclosure(); 
    
    useDetectKeyDown(
        (e) => {
            console.log("Escape pressed!");
            disclosure.close();
        },
        "Escape",
        disclosure.opened,
    );
    
    return ( 
        <Button
            onClick={() => disclosure.update(!disclosure.opened)}
        > 
            { disclosure.opened 
                ? "Press `Escape`"
                : "Don't press `Escape`"
            }
        </Button>
    )
}

---

Parameters

Parameter	Type	Description
callback (required)	(e: KeyboardEvent) => void	The function to call when the key is pressed.
keys (required)	string | string[]	A key or array of keys to listen for.
runCheck	boolean	Whether to listen for keyboard events.
deps	any[]	Any dependencies to pass to the useEffect hook.