From 07d48a83e70d6eed5a4c00dbcf100b738b87ef9c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 16:46:36 +0000
Subject: [PATCH 1/2] Initial plan


From 74db7d76108bb1a72eaa7cce4d6f562bfa6a2c03 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 16:50:05 +0000
Subject: [PATCH 2/2] Add guard to normalizeKeyName() for undefined keys and
 changeset

Agent-Logs-Url: https://github.com/TanStack/hotkeys/sessions/0f2d34d9-1daf-4199-b2ad-bb1291fc11c4

Co-authored-by: KevinVandy <28243511+KevinVandy@users.noreply.github.com>
---
 .changeset/guard-normalize-key-name-undefined.md | 5 +++++
 packages/hotkeys/src/constants.ts                | 3 +++
 packages/hotkeys/tests/parse.test.ts             | 7 +++++++
 3 files changed, 15 insertions(+)
 create mode 100644 .changeset/guard-normalize-key-name-undefined.md

diff --git a/.changeset/guard-normalize-key-name-undefined.md b/.changeset/guard-normalize-key-name-undefined.md
new file mode 100644
index 00000000..25d3b3d5
--- /dev/null
+++ b/.changeset/guard-normalize-key-name-undefined.md
@@ -0,0 +1,5 @@
+---
+"@tanstack/hotkeys": patch
+---
+
+Add guard to `normalizeKeyName()` for undefined/falsy key values to prevent errors when browser extensions, accessibility tools, or certain OS/browser combinations synthesize key events with undefined `event.key`.
diff --git a/packages/hotkeys/src/constants.ts b/packages/hotkeys/src/constants.ts
index 5eb21911..f89628ed 100644
--- a/packages/hotkeys/src/constants.ts
+++ b/packages/hotkeys/src/constants.ts
@@ -455,6 +455,9 @@ export function isSingleLetterKey(key: string): boolean {
  * ```
  */
 export function normalizeKeyName(key: string): string {
+  // key can be undefined in rare cases
+  // (browser extensions synthesizing key events, accessibility tools, certain OS/browser combinations).
+  if (!key) return ''
   // Check aliases first
   if (key in KEY_ALIASES) {
     return KEY_ALIASES[key]!
diff --git a/packages/hotkeys/tests/parse.test.ts b/packages/hotkeys/tests/parse.test.ts
index c4bd2bdb..40b8c8e6 100644
--- a/packages/hotkeys/tests/parse.test.ts
+++ b/packages/hotkeys/tests/parse.test.ts
@@ -267,6 +267,13 @@ describe('isModifierKey', () => {
   })
 })
 
+describe('normalizeKeyName', () => {
+  it('returns empty string for falsy input (undefined coerced, empty string)', () => {
+    expect(normalizeKeyName('')).toBe('')
+    expect(normalizeKeyName(undefined as unknown as string)).toBe('')
+  })
+})
+
 describe('rawHotkeyToParsedHotkey', () => {
   it('should convert minimal RawHotkey (key only)', () => {
     const result = rawHotkeyToParsedHotkey({ key: 'Escape' })