Scopes & Dispatch Behavior

Understand how Keybound resolves shortcuts, modal isolation, and browser eligibility.

Modal Scopes & Isolation

When a modal dialog or drawer is active, you don't want background page hotkeys triggering by accident. Wrapping modal content in <KeyboundScope modal active={open}> isolates the keyboard tree cleanly.

// 1. Import scope component from react-keybound
import { KeyboundScope } from "react-keybound";

// 2. Modal component managing isolated keyboard hierarchy
function ProjectModal({ open, onClose }) {

  return (

    // Modal scope suppresses background shortcuts and prioritizes nested bindings
    <KeyboundScope active={open} modal name="project-dialog">

      <div role="dialog">

        {/* Alt+S inside modal triggers modal save, not page save */}
        <button onClick={saveModal}>&Save dialog</button>

        {/* Alt+C triggers modal close */}
        <button onClick={onClose}>&Close</button>

      </div>

    </KeyboundScope>

  );

}

Dispatch-Time Eligibility

Keybound checks the actual DOM state when the key is pressed, not when registered. If a button is disabled, inert, or hidden behind CSS (display: none), it is ignored.

// 1. Disabled or inert controls are skipped at dispatch time
<button disabled onClick={deleteItem}>&Delete</button>

// 2. Typing in text fields suppresses normal shortcuts automatically
<input placeholder="Type something..." />

// 3. Opt-in with allowInInput if you want an in-field shortcut
useHotkey("escape", clearInput, { allowInInput: true });

Summary of Rules

Deepest active scope wins collisions.
Focused element has highest priority within the active scope.
Composition, IME, and repeated keys do not trigger accidental actions.