From 3857e0784ce1b71704e283259fcae01870b26893 Mon Sep 17 00:00:00 2001
From: Pavan Shinde <pavann97@gmail.com>
Date: Thu, 19 Feb 2026 13:26:52 +0000
Subject: [PATCH 1/2] docs: add React troubleshooting guide

---
 docs/config.json                              |  4 ++
 .../framework/react/guides/troubleshooting.md | 59 +++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 docs/framework/react/guides/troubleshooting.md

diff --git a/docs/config.json b/docs/config.json
index b2dc055..062abb1 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -60,6 +60,10 @@
             {
               "label": "Formatting & Display",
               "to": "framework/react/guides/formatting-display"
+            },
+            {
+              "label": "Troubleshooting",
+              "to": "framework/react/guides/troubleshooting"
             }
           ]
         }
diff --git a/docs/framework/react/guides/troubleshooting.md b/docs/framework/react/guides/troubleshooting.md
new file mode 100644
index 0000000..89d2987
--- /dev/null
+++ b/docs/framework/react/guides/troubleshooting.md
@@ -0,0 +1,59 @@
+---
+title: Troubleshooting
+id: troubleshooting
+---
+
+# Troubleshooting
+
+This page collects the most common reasons hotkeys don’t fire (or fire unexpectedly) and how to fix them.
+
+## My hotkey doesn’t fire while typing in an input/textarea
+
+By default, TanStack Hotkeys **ignores** keyboard events that originate from common text input elements (for example `input`, `textarea`, and contenteditable regions). This prevents hotkeys from breaking normal typing.
+
+**Fix options:**
+
+- Bind the hotkey to a more specific target (for example a focused panel) instead of `document`.
+- Use a dedicated UI (like a command palette) that intentionally captures key events.
+
+## My hotkey fires even when focus is inside an input
+
+If a hotkey is firing while the user is typing, it usually means the event is being listened to on a target that’s too broad (or you’re bypassing the default input filtering).
+
+**Fix:**
+
+- Make sure you’re using the default input filtering behavior.
+- Prefer scoping hotkeys to a container (panel/dialog) that must be focused.
+
+## The same hotkey fires twice
+
+Common causes:
+
+- In React development (especially with Strict Mode), effects and subscriptions can run more than once, which can expose missing cleanup or double-registration.
+- You accidentally registered the same hotkey in multiple components.
+
+**Fix:**
+
+- Ensure hotkeys are registered in exactly one place.
+- If you need per-route registration, clean up registrations on unmount.
+
+## Hotkeys behave differently on macOS vs Windows/Linux
+
+Use `Mod` when you mean “Cmd on macOS, Ctrl elsewhere”.
+
+Examples:
+
+- `Mod+K` (Cmd+K on macOS, Ctrl+K on Windows/Linux)
+- `Mod+Shift+P`
+
+## My hotkey uses a symbol key and doesn’t match `event.key`
+
+Some keyboard layouts can produce characters where `event.key` isn’t the physical key you expect (for example when using Option/Alt combinations).
+
+**Tip:** Prefer the library helpers that normalize key names and hotkey strings instead of comparing raw `event.key` yourself.
+
+## Still stuck?
+
+If you can share a minimal reproduction, discussions are the fastest way to get help:
+
+- https://github.com/tanstack/hotkeys/discussions

From 0a8c3d36106f3be6683e7d9acda33650f8d22e1c Mon Sep 17 00:00:00 2001
From: Pavan Shinde <pavann97@gmail.com>
Date: Thu, 19 Feb 2026 13:39:45 +0000
Subject: [PATCH 2/2] docs: clarify target scoping guidance

---
 docs/framework/react/guides/troubleshooting.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/framework/react/guides/troubleshooting.md b/docs/framework/react/guides/troubleshooting.md
index 89d2987..7b43402 100644
--- a/docs/framework/react/guides/troubleshooting.md
+++ b/docs/framework/react/guides/troubleshooting.md
@@ -13,7 +13,8 @@ By default, TanStack Hotkeys **ignores** keyboard events that originate from com
 
 **Fix options:**
 
-- Bind the hotkey to a more specific target (for example a focused panel) instead of `document`.
+- If you bind the hotkey to a specific element (instead of `document`), make sure that element can actually receive key events (it typically needs to be focusable and focused).
+- If you want hotkeys to work globally, bind to `document` and rely on the default input filtering.
 - Use a dedicated UI (like a command palette) that intentionally captures key events.
 
 ## My hotkey fires even when focus is inside an input
@@ -22,8 +23,8 @@ If a hotkey is firing while the user is typing, it usually means the event is be
 
 **Fix:**
 
-- Make sure you’re using the default input filtering behavior.
-- Prefer scoping hotkeys to a container (panel/dialog) that must be focused.
+- Check whether input filtering has been disabled, or whether you’re attaching listeners to a target that’s too broad (like `document`).
+- If you intentionally scope hotkeys to a container (panel/dialog), ensure that container is focusable and focused when you expect hotkeys to work.
 
 ## The same hotkey fires twice