@keybindy/react
Version:
Keybindy for React: Simple, scoped keyboard shortcuts that require little setup. designed to smoothly blend in with your React applications, allowing for robust keybinding functionality without the overhead.
190 lines (142 loc) • 8.38 kB
Markdown
# @keybindy/react
@keybindy/react is the official React integration for the [Keybindy](https://www.npmjs.com/package/@keybindy/core) keyboard shortcut system. Built on top of `@keybindy/core`, this package brings powerful and scoped keyboard bindings to your React applications — with components and hooks tailored to React’s architecture.
[](https://www.npmjs.com/package/@keybindy/react)
[](https://opensource.org/licenses/MIT)
---
## 🧠 What is @keybindy/react?
While `@keybindy/core` gives you the underlying logic to register and manage shortcuts in any JavaScript environment, **@keybindy/react** wraps it in a React-friendly API with scoped context, declarative components, and hooks for full control.
---
## Installation
```bash
# npm
npm install @keybindy/react
# yarn
yarn add @keybindy/react
# bun
bun add @keybindy/react
```
---
## Usage
#### `<Keybindy />` component
The core declarative component. Register all your scoped or global shortcuts with ease.
| Prop | Type | Default | Description |
| ----------------- | -------------------- | ----------- | -------------------------------------------------------------- |
| `logs` | `boolean` | `false` | Whether to enable debug logs in the console. |
| `onShortcutFired` | `fn(info: Shortcut)` | `undefined` | Optional callback to handle shortcut firing events. |
| `disabled` | `boolean` | `false` | Whether to disable all shortcuts within the component's scope. |
| `scope` | `string` | `global` | The scope to apply the shortcuts to. |
| `shortcuts` | `Shortcut[]` | `[]` | Array of shortcut objects to register. |
| `children` | `React.ReactNode` | `undefined` | The content to render inside the component. |
##### Example
```ts
import { Keybindy } from '@keybindy/react';
<Keybindy
scope="global"
shortcuts={[
{
keys: ['A'],
handler: () => console.log('A pressed'),
options: {
preventDefault: true,
},
},
{
keys: ['O', 'P'],
handler: () => setIsOpen(true),
options: {
sequenceDelay: 1000,
sequential: true,
preventDefault: true,
},
},
{
keys: ['R'],
handler: () => window.open('https://react.dev', '_blank'),
options: {
preventDefault: true,
},
},
]}
/>;
```
#### `<ShortcutLabel />` component
A lightweight UI component to render visually styled shortcut hints.
| Prop | Type | Default | Description |
| ----------- | ---------------------------------------------- | ----------- | ---------------------------------------------- |
| `keys` | `Keys` | `[]` | The key combination(s) to display. |
| `renderKey` | `fn(key: string, index: number, keys: Keys[])` | `undefined` | Custom renderer for each key badge or segment. |
##### Example
```ts
import { ShortcutLabel } from '@keybindy/react';
<ShortcutLabel
keys={['ctrl', 'alt', 'delete']}
renderKey={(key, i, all) => (
<>
<span style={{ color: '#00eaff' }}>{key.toUpperCase()}</span>
{i < all.length - 1 && <span style={{ opacity: 0.5 }}> + </span>}
</>
)}
/>;
```
#### `useKeybindy` Hook
A powerful hook that gives you full control over the shortcut system via the ShortcutManager under the hood. Best for dynamic or advanced use cases.
##### Available methods
| Method | Description |
| --------------------------------------------------------------------- | -------------------------------------------- |
| [`register()`](https://github.com/keybindy/core#register) | Register a shortcut |
| [`unregister()`](https://github.com/keybindy/core#unregister) | Unregister a shortcut |
| [`enable()`](https://github.com/keybindy/core#enable--disable--toggle) | Enable a specific shortcut |
| [`disable()`](https://github.com/keybindy/core#enable--disable--toggle) | Disable a specific shortcut |
| [`toggle()`](https://github.com/keybindy/core#enable--disable--toggle) | Toggle a shortcut on/off |
| [`enableAll()`](https://github.com/keybindy/core#enableall--disableall) | Enable all shortcuts (global or scoped) |
| [`disableAll()`](https://github.com/keybindy/core#enableall--disableall) | Disable all shortcuts (global or scoped) |
| [`setScope()`](https://github.com/keybindy/core#setactivescope) | Set the active scope |
| [`resetScope()`](https://github.com/keybindy/core#resetScope) | Reset to default scope |
| [`getScopes()`](https://github.com/keybindy/core#getScopes) | Get all defined scopes |
| [`getActiveScope()`](https://github.com/keybindy/core#getActiveScope) | Get the current active scope |
| [`popScope()`](https://github.com/keybindy/core#popScope) | Remove the top scope from the scope stack |
| [`pushScope()`](https://github.com/keybindy/core#pushScope) | Push a new scope onto the scope stack |
| [`getCheatSheet()`](https://github.com/keybindy/core#getCheatsheet) | Retrieve all shortcuts (optionally by scope) |
| [`onTyping()`](https://github.com/keybindy/core#onTyping) | Listen to every key press |
| [`destroy()`](https://github.com/keybindy/core#destroy) | Tear down the current manager instance |
| [`clear()`](https://github.com/keybindy/core#clear) | Unregister all shortcuts |
| [`getScopeInfo()`](https://github.com/keybindy/core#getScopeInfo) | Retrieve metadata about a specific scope |
| [`isScopeActive()`](https://github.com/keybindy/core#isScopeActive) | Check if a scope is currently active |
> _All methods mirror `@keybindy/core` with a React-friendly API._
##### Example
```ts
import { useKeybindy } from '@keybindy/react';
const { register, unregister, setScope, getCheatSheet } = useKeybindy();
React.useEffect(() => {
register(
['ctrl', 'k'],
() => {
console.log('Shortcut fired!');
},
{
scope: 'editor',
preventDefault: true,
}
);
return () => {
unregister(['ctrl', 'k'], 'editor');
};
}, []);
```
---
## Reference
If you're looking for more detailed implementation logic and architecture, check out the [@keybindy/core](https://www.npmjs.com/package/@keybindy/core) documentation for an in-depth look at how shortcut handling works under the hood.
---
## 🧩 Want More?
This package is part of the Keybindy Ecosystem:
| Package | Description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [`@keybindy/core`](https://npmjs.com/package/@keybindy/core) | The core JavaScript library. Framework-agnostic, fully typed, and tree-shakable. |
| [`@keybindy/react`](https://npmjs.com/package/@keybindy/react) | React bindings with hooks and components for easy integration. |
| _Coming Soon_ | Stay tuned! |
---
## Contributing
PRs, issues, and ideas are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
If you're adding a new framework integration (like Vue or Svelte), feel free to open a draft PR — we'd love to collaborate.
---
> _Might be new in the shortcut game, but Keybindy’s here to change the frame — fast, flexible, and ready to claim. 🎯_