🚀 @hookies/key-bindings

A lightweight React Hook for adding keyboard shortcuts to your application. Easily bind keyboard combinations to functions without extra configuration!

📖 Table of Contents

📦 Installation
🎮 Playground - Test Key Bindings Online
🔥 Usage
🎯 OS-Specific Shortcuts
⚙ API Reference
🛠 Advanced Features (Coming Soon)
🚀 Contributing
📜 License
⭐ Support & Feedback

📦 Installation

Install the package using npm:

npm install @hookies/key-bindings

or using yarn:

yarn add @hookies/key-bindings

🎮 Playground - Test Key Bindings Online

Want to try out keyboard shortcuts before using them in your project? Use our interactive playground to generate the function dynamically!

🛠 🔗 Open Playground

Press any key combination (e.g., Meta + X, Ctrl + Shift + A).
The playground shows the generated function with the exact keys pressed.
Copy the generated function and paste it into your project.

📌 Example Output in Playground
If you press Meta + X, the playground will generate:

useShortcut(["meta", "x"], func);

Just copy and use in your code! 🚀

🔥 Usage

Import the useShortcut or useShortcutExtended hook and bind a keyboard shortcut to an action.

Basic Example: Modifier-Based Shortcuts (`useShortcut`)

import React, { useState } from "react";
import { useShortcut } from "@hookies/key-bindings";

const App = () => {
  const [message, setMessage] = useState("Press Ctrl+8");

  useShortcut(["Ctrl", "8"], () => setMessage("Shortcut Triggered!"));

  return <h1>{message}</h1>;
};

export default App;

Example: Any Key Combination (`useShortcutExtended`)

import { useState } from "react";
import { useShortcutExtended } from "@hookies/key-bindings";

const App = () => {
  const [message, setMessage] = useState("Press A + S");

  useShortcutExtended(["a", "s"], () => setMessage("Shortcut Triggered!"));

  return <h1>{message}</h1>;
};

export default App;

🎯 OS-Specific Shortcuts

This library does not auto-adjust shortcuts for Mac vs Windows. If you need platform-specific bindings, use getOS().

import { useShortcut, getOS } from "@hookies/key-bindings";

const os = getOS();
const shortcutKeys = os === "MacOS" ? ["Meta", "8"] : ["Ctrl", "8"];

useShortcut(shortcutKeys, () => console.log("Shortcut Triggered!"));

⚙ API Reference

`useShortcut(keys: string[], callback: () => void, options?: UseShortcutOptions)`

keys (string[]) – Array of keys that should trigger the shortcut (e.g., ["Ctrl", "8"]).
callback (function) – Function to execute when the shortcut is triggered.
options (optional)
- preventDefault (boolean) – Prevents default browser behavior (default: false).

Example: Prevent Default Behavior

useShortcut(["Ctrl", "S"], () => console.log("Save triggered"), { preventDefault: true });

`useShortcutExtended(keys: string[], callback: () => void, options?: UseShortcutOptions)`

This hook detects any key combination, including non-modifier keys.

keys (string[]) – Array of keys to trigger the shortcut (e.g., ["a", "s"]).
callback (function) – Function to execute when the shortcut is triggered.
options (optional)
- preventDefault (boolean) – Prevents default browser behavior (default: false).

Example: Detecting Non-Modifier Key Combinations

useShortcutExtended(["a", "s"], () => console.log("Pressed A + S!"));
useShortcutExtended(["x", "z", "q"], () => console.log("Pressed X + Z + Q!"));

`getOS()`

Returns the user's operating system as a string: "Windows", "MacOS", "Linux", "Android", "iOS", or "Unknown".

Example

console.log(getOS()); // Outputs: "MacOS"

🛠 Advanced Features (Coming Soon)

✅ Support for multiple shortcut registrations in a single call.
✅ Global shortcut manager.
✅ Dynamic shortcut customization via props.

🚀 Contributing to Hookies Key Bindings

🎉 Thank you for considering contributing to Hookies Key Bindings!
We welcome all contributions, whether it's bug fixes, feature additions, documentation updates, or tests.

1️⃣ Fork the Repository

Click on the "Fork" button in the top-right corner of the repository.

Clone your forked repository:

git clone https://github.com/YOUR-USERNAME/-hookies-key-bindings.git
cd -hookies-key-bindings

2️⃣ Set Up the Project

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

3️⃣ Create a New Branch

Before making any changes, create a new branch:

git checkout -b feature/your-feature-name

or for bug fixes:

git checkout -b fix/your-fix-name

4️⃣ Make Changes and Test

Implement your feature or fix.
Ensure the build succeeds:
```
npm run build
```
If you modified TypeScript files, check types:
```
tsc --noEmit
```

5️⃣ Commit and Push

Commit your changes:

git commit -m "✨ Add new feature: Keyboard shortcuts for Mac"

Push your changes:

git push origin feature/your-feature-name

Open a Pull Request (PR) and submit your changes! 🚀

📜 License

This project is licensed under the ISC License.

⭐ Support & Feedback

If you like this project, give it a ⭐ on GitHub!
For issues or feature requests, open an issue.

Package detail