@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/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

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/core with 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. 🎯