Allow passing ref to Keybinding

Author: martpie

README.md

@@ -22,6 +22,15 @@ Get the eventKey keyCode and log it on `keyUp` on the window element
 <KeyBinding onKey={ (e) => { console.log(e.keyCode) } } type='keyup' target={ window } />
 ```
 
+Scope the listener to a container element via a React ref (only fires when focus is inside the container)
+``` JSX
+const containerRef = useRef(null);
+
+<div ref={containerRef}>
+  <KeyBinding onKey={ (e) => { console.log(e.keyCode) } } target={ containerRef } />
+</div>
+```
+
 Have a look at options.
 
 ### Options
@@ -32,7 +41,7 @@ All properties except `onKey` are optional.
 |----------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------|
 | `onKey` (required)               | the function executed after a key event                                                                              | n/a           |
 | `type`                           | keyup or keydown                                                                                                     | `'keydown'`   |
-| `target`                         | the element you want to attach the event to, it can be an **existing** DOM element or a CSS selector (in that case, you will need to add a `tabIndex='0'` to your element, otherwise the event won't be caught) | `document`    |
+| `target`                         | the element you want to attach the event to: an **existing** DOM element, a CSS selector (you will need to add `tabIndex='0'` to your element, otherwise the event won't be caught), or a **React ref** (`RefObject<HTMLElement>`) — if a ref is passed and `.current` is `null`, the listener is silently skipped | `document`    |
 | `preventInputConflict`           | prevent onKey from firing if you have an onChange on an input, a textarea or a select                                | `false`       |
 | `preventContentEditableConflict` | prevent onKey from firing if the user is editing the DOM via contenteditable="true", usually used by WYSIWYG editors | `false`       |
 | `preventDefault`                 | prevent event default                                                                                                | `false`       |

src/keybinding.tsx

@@ -1,9 +1,9 @@
-import { useCallback, useEffect } from 'react';
+import { type RefObject, useCallback, useEffect } from 'react';
 
 export type KeybindingProps = {
   onKey: (e: KeyboardEvent) => void;
   type?: 'keydown' | 'keyup';
-  target?: string | HTMLElement | Document | Window;
+  target?: string | HTMLElement | Document | Window | RefObject<HTMLElement>;
   preventInputConflict?: boolean;
   preventContentEditableConflict?: boolean;
   preventDefault?: boolean;
@@ -12,12 +12,19 @@ export type KeybindingProps = {
 
 const TARGETS_BLACKLIST = ['textarea', 'input', 'select'];
 
+function isRefObject(
+  target: NonNullable<KeybindingProps['target']>,
+): target is RefObject<HTMLElement> {
+  return typeof target === 'object' && 'current' in target;
+}
+
 /**
- * Get the actual target to which we should attach the event
+ * Get the actual target to which we should attach the event.
+ * Returns null if a ref is passed but not yet mounted.
  */
 function getTarget(
   target: NonNullable<KeybindingProps['target']>,
-): HTMLElement | Document | Window {
+): HTMLElement | Document | Window | null {
   if (typeof target === 'string') {
     const element = document.querySelector<HTMLElement>(target);
     if (!element) {
@@ -29,6 +36,10 @@ function getTarget(
     return element;
   }
 
+  if (isRefObject(target)) {
+    return target.current;
+  }
+
   return target;
 }
 
@@ -83,6 +94,8 @@ export default function Keybinding(props: KeybindingProps) {
   useEffect(() => {
     const actualTarget = getTarget(target);
 
+    if (!actualTarget) return;
+
     actualTarget.addEventListener(type, onKeyEvent as EventListener);
 
     return () => {