Feature: support physical key (event.code) matching for non-Latin IME input methods

[HwangSB]

TanStack Hotkeys version

0.7.0

Framework/Library version

React 19

Describe the bug and the steps to reproduce it

When a non-Latin input method is active (e.g., Korean, Japanese, Chinese, Russian IME), single-key hotkeys do not fire because event.key produces a non-Latin character instead of the expected ASCII letter.

For example, with Korean input active, pressing the physical A key produces:

• event.key = 'ㅁ'
• event.code = 'KeyA'

So a hotkey registered as A will not match.

The current matching logic in matchesKeyboardEvent (match.ts) trusts the keyboard layout for non-ASCII letters without Alt:

if (
  isSingleLetterKey(eventKey) &&
  (/^[A-Za-z]$/.test(eventKey) || !event.altKey)
) {
  return false  // trusts layout, never reaches event.code fallback
}

This correctly supports alternative Latin layouts (Dvorak, Colemak, AZERTY). However, for IME-based input methods where the physical layout is QWERTY but the output characters are non-Latin, the event.code fallback is never reached, and the hotkey silently fails.

Steps to reproduce:

1. Switch OS input method to Korean (or any non-Latin IME)
2. Register useHotkey('A', callback)
3. Press the physical A key
4. Callback never fires

This affects all non-Latin IME users globally: Korean, Japanese, Chinese, Russian, Arabic, Thai, and more. Users frequently switch between their native input method and English throughout their workflow and expect single-key shortcuts to work without manually switching input language first.

Proposed solution

An explicit opt-in option for event.code based (physical key) matching:

// Per-registration
useHotkey('A', callback, { matchBy: 'code' })

// Or via useHotkeys
useHotkeys(
  [
    { hotkey: 'A', callback: handleA },
    { hotkey: 'S', callback: handleS },
  ],
  { matchBy: 'code' }
)

When matchBy: 'code' is set, matchesKeyboardEvent would compare the hotkey against event.code (e.g., 'A' matches KeyA) instead of event.key. The default remains 'key' to preserve current behavior.

This avoids the conflict with automatic fallback approaches (see #53) because the consumer explicitly opts in per registration. Applications that need layout-aware matching (Dvorak, Colemak) keep the default 'key' behavior, while applications that need physical key matching can opt in.

Related

• Add support for international keyboard layouts #65 (Discussion: Add support for international keyboard layouts)

Your Minimal, Reproducible Example - (Sandbox Highly Recommended)

No response

Screenshots or Videos (Optional)

No response

Do you intend to try to help solve this bug with your own PR?

• I intend to try to help solve this bug with my own PR

Terms & Code of Conduct

• I agree to follow this project's Code of Conduct
• I understand that if my bug cannot be reliable reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.