@hookies/key-bindings v2.0.4

🚀 @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
  • useShortcut
  • useShortcutExtended
  • getOS
• 🛠 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.