@keybindy/react v1.0.1
@keybindy/react
@keybindy/react is the official React integration for the Keybindy 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.
🧠 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
# npm
npm install @keybindy/react
# yarn
yarn add @keybindy/react
# bun
bun add @keybindy/reactUsage
<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
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
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() | Register a shortcut |
unregister() | Unregister a shortcut |
enable() | Enable a specific shortcut |
disable() | Disable a specific shortcut |
toggle() | Toggle a shortcut on/off |
enableAll() | Enable all shortcuts (global or scoped) |
disableAll() | Disable all shortcuts (global or scoped) |
setScope() | Set the active scope |
resetScope() | Reset to default scope |
getScopes() | Get all defined scopes |
getActiveScope() | Get the current active scope |
popScope() | Remove the top scope from the scope stack |
pushScope() | Push a new scope onto the scope stack |
getCheatSheet() | Retrieve all shortcuts (optionally by scope) |
onTyping() | Listen to every key press |
destroy() | Tear down the current manager instance |
clear() | Unregister all shortcuts |
getScopeInfo() | Retrieve metadata about a specific scope |
isScopeActive() | Check if a scope is currently active |
All methods mirror
@keybindy/corewith a React-friendly API.
Example
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 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 | The core JavaScript library. Framework-agnostic, fully typed, and tree-shakable. |
@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 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. 🎯