npm package: @gammarkin/use-shorcut
Description: A lightweight and dependency-free React utility for handling keyboard shortcuts, either globally or scoped to specific elements.
Latest version: 0.0.6

# @gammarkin/use-shortcut

A lightweight and dependency-free React utility for handling keyboard shortcuts, either globally or scoped to specific elements.

---

## Installation

```bash
npm install @gammarkin/use-shortcut
```

## Parameters

### keys

keys is the first param, and it should be a string, or a array of strings. Wich will call the funcion if the given key is pressed.

The keys are always checked no matter if upper or lowercase

### onKey

onKey is the second param and it should be a function, that will execute once the given key is pressed inside the components that handle the listener

### options

options is the third param. It is optional, and it should be an object with the following keys:

```tsx
	{
		preventDefault?: boolean; // calls preventDefault inside the element
		debounceInput?: boolean; // makes the input have a delay
		includeDomSelectors?: string[]; // only listens to the selectors
		excludeDomSelectors?: string[]; // does not listens to the selectors
	};
```

by default, the options come as:

```tsx
{
		preventDefault = true,
		debounceInput = false,
		includeDomSelectors = [],
		excludeDomSelectors = [],
}
```

---

## Usage

### 1. Using the `useShortcut` hook

Use the hook directly inside a function on your component and attach the handler to a DOM element.

```tsx
import React, {useEffect} from 'react';
import {useShortcut} from '@gammarkin/use-shortcut';

function Example() {
	const keys = ['a', 'b', 'c'];
	const onKey = (item) => `logging ${item}`;
	const options = {};

	useEffect(() => {
		const handleKeyPress = useShortcut(keys, onKey, options);

		window.addEventListener('keydown', handleKeyPress);

		return () => {
			window.removeEventListener('keydown', handleKeyPress);
		};
	}, [keys, onKey]);

	return <input type="text" placeholder="Press A" />;
}
```

PS: Use useGlobalShortcut if you need the keys running all time. Just pass the props and call the function like

```tsx
import React, {useEffect} from 'react';
import {useGlobalShortcut} from '@gammarkin/use-shortcut';

function Example() {
	const keys = ['a', 'b', 'c'];
	const onKey = (item) => `logging ${item}`;
	const options = {};

	useEffect(() => {
		const handleKeyPress = useGlobalShortcut(keys, onKey, options);
	}, [keys, onKey]);

	return <input type="text" placeholder="Press A" />;
}
```

---

### 2. Using the `Shortcut` component

Wrap any element and the shortcut will only trigger when that element (or its children) is focused.

IMPORTANT: not passing the keys, onKey props will break your application.

```tsx
import React from 'react';
import {Shortcut} from '@gammarkin/use-shortcut';

export default function App() {
	return (
		<Shortcut
			keys={['x']}
			onKey={(key) => alert(`Shortcut triggered: ${key}`)}
			options={{preventDefault: true}}
		>
			<input>Press X while focused here</input>
		</Shortcut>
	);
}
```

---

## ⚙️ Types

### useShortcut

```tsx
useShortcut(
  keys: string | string[],
  onKey: (key: string, event: KeyboardEvent) => void,
  options?: {
    preventDefault?: boolean;
  }
): (event: KeyboardEvent) => void
```

### Shortcut component props

```tsx
<Shortcut
	keys="a" // or ["a", "A"]
	onKey={(key, event) => {}}
	options={{
		preventDefault: true,
	}}
>
	{children}
</Shortcut>
```

---

## 📌 Notes

- No external dependencies
- Fully typed with TypeScript

---

## 🧑‍💻 Author

Made by [@gammarkin](https://github.com/gammarkin)