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 });

Semantic Character Matching & macOS

Mnemonics are semantic character shortcuts: Keybound matches KeyboardEvent.key, respecting the user's active keyboard layout and remapping. It never infers characters from physical key positions (event.code) or legacy key codes.

On macOS and iPadOS, the Option key acts as an alternative glyph modifier and dead-key composer (e.g. Option+S produces “ß”, Option+X produces “≈”, and Option+E produces a dead key). Because Keybound adheres strictly to semantic matching, these glyphs do not match ASCII letters under an alt modifier.

To provide seamless cross-platform ergonomics, <KeyboundProvider> defaults to mnemonicModifier="auto". This automatically resolves to Alt on Windows and Linux, and mod (⌘ Command) on macOS and iPadOS.

While mod (⌘) provides a native Mac experience, browsers reserve certain shortcuts (such as ⌘L for WebKit's address bar, ⌘W to close tabs, and ⌘R to reload) that web apps cannot intercept. You can provide a granular platform map to use Control (⌃) on Mac for 100% collision-free accelerators:

mnemonicModifier={{ mac: 'ctrl', windows: 'alt', linux: 'alt' }}

Explicitly configuring mnemonicModifier="alt" on an Apple platform will emit a development warning (mac-alt-mnemonic), which can be suppressed via the warnings prop.

Summary of Rules

Semantic matching via KeyboardEvent.key; physical key codes are never used.
Deepest active scope wins collisions.
Focused element has highest priority within the active scope.
Composition, dead-key, IME, AltGraph, and repeated keys do not trigger accidental actions.