use_keys

A simple library to make using key events in React reactive, enabling the creation of keyboard-driven web applications.

Features

• Reactive Key Event Handling: Use key events reactively within your React components.
• Simple API: Easy-to-use hooks and components for handling key events.
• Key State Management: Manage the state of keys, whether they are pressed or released.
• Flexible Usage: Can be used for simple key state checking or more complex interactions.

Installation

You can install use_keys via npm:

npm install @michaseyi/use_keys

Example Usage

Using useKeys reactively

import { KeyProvider, useKeys, KeyState, isReleased } from "@michaseyi/use_keys"

function TestKeys() {
	const keys = useKeys()

	const keyW = keys.use.KeyW()

	return <div>{isReleased(keyW) ? "Key W Released" : "Key W Pressed"}</div>
}

function App() {
	return (
		<KeyProvider>
			<TestKeys />
		</KeyProvider>
	)
}

Using useKeys like regular event listeners

import { KeyProvider, useKeys, KeyState } from "@michaseyi/use_keys"

function TestKeys() {
	const keys = useKeys()

	const arrowDown = keys.use.ArrowDown()
	const arrowUp = keys.use.ArrowUp()

	const [count, setCount] = useState(0)

	useEffect(() => {
		if (isPressed(arrowUp)) {
			setCount(count + 1)
		}
	}, [arrowUp])

	useEffect(() => {
		if (isPressed(arrowDown)) {
			setCount(count - 1)
		}
	}, [arrowDown])

	return <div>Clicked {count} times</div>
}

function App() {
	return (
		<KeyProvider>
			<TestKeys />
		</KeyProvider>
	)
}

Using useKeys with custom key bindings and also disabling default key combo behaviour

import { Key, isPressed, useKeys } from "@michaseyi/use_keys"

function App() {

	// useKeys now takes in a function that allows you to disable default key combo behaviour set by the browser
	// When the function returns true, the default behaviour for the pressed keys will be disabled
  // For example, below we are disabling the default behaviour of the browser when the user presses Ctrl + Shift + P or Ctrl + P
	const keys = useKeys(
		(state) =>
			(isPressed(state.Control) && isPressed(state.Shift) && isPressed(state.KeyP)) ||
			(isPressed(state.Control) && isPressed(state.KeyP))
	)

	const arrowUp = keys.use.ArrowUp()

	const arrowDown = keys.use.ArrowDown()

	const combo = keys.use.Combo(Key.Ctrl, Key.Shift, Key.KeyP)

	return (
		<>
			{isPressed(combo) && <div>combo pressed</div>}
		</>
	)
}

API Reference

useKeys

The useKeys hook provides access to key event handling functionality within your components.

Usage

const keys = useKeys()

Methods

• use.keyName(): Returns the state of a specific key. Replace keyName with the name of the key (e.g., KeyW, ArrowUp, etc.).

KeyProvider

The KeyProvider component wraps your components and provides access to key event handling functionality via context.

Usage

<KeyProvider>{/* Your components */}</KeyProvider>

isPressed

The isPressed function checks if a key is pressed.

isReleased

The isReleased function checks if a key is released.