@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. 🎯