Allow including modifier keys in handler's keys array

packages/documentation/docs/api/use-hotkeys.mdx

@@ -171,6 +171,7 @@ const options = {
   document: undefined,
   ignoreModifiers: false,
   useKey: false,
+  includeModifiersInKeys: false,
 };
 ```
 
@@ -381,6 +382,17 @@ useKey: boolean // default: false
 This option allows us to listen to the produced key instead of the key code. This is useful if we want to listen to a
 specific key (e.g. `!`, `:`, `%`, etc.) and don't care about how the user produces that key.
 
+
+##### `includeModifiersInKeys`
+
+```ts
+includeModifiersInKeys: boolean // default: false
+```
+
+When set to `true`, the `keys` property of the `handler` object will include the modifier keys (e.g. `shift`, `ctrl`, etc.)
+This is useful if we want to know which modifier keys were pressed in addition to the main key. For example, if the user
+presses `ctrl+s`, the `keys` property will contain `['ctrl', 's']` instead of just `['s']`.
+
 ***
 
 ### `deps`

packages/react-hotkeys-hook/src/lib/parseHotkeys.ts

@@ -39,6 +39,7 @@ export function parseHotkey(
   sequenceSplitKey = '>',
   useKey = false,
   description?: string,
+  includeModifiersInKeys = false,
 ): Hotkey {
   let keys: string[] = []
   let isSequence = false
@@ -65,11 +66,11 @@ export function parseHotkey(
     useKey,
   }
 
-  const singleCharKeys = keys.filter((k) => !reservedModifierKeywords.includes(k))
+  const filteredKeys = includeModifiersInKeys ? keys : keys.filter((k) => !reservedModifierKeywords.includes(k))
 
   return {
     ...modifiers,
-    keys: singleCharKeys,
+    keys: filteredKeys,
     description,
     isSequence,
   }

packages/react-hotkeys-hook/src/lib/types.ts

@@ -70,6 +70,8 @@ export type Options = {
   sequenceTimeoutMs?: number
   // The character to split the sequence of keys. (Default: >)
   sequenceSplitKey?: string
+  // Include modifier keys in `keys` array (Default: false)
+  includeModifiersInKeys?: boolean
 }
 
 export type OptionsOrDependencyArray = Options | DependencyList

packages/react-hotkeys-hook/src/lib/useHotkeys.ts

@@ -103,6 +103,7 @@ export default function useHotkeys<T extends HTMLElement>(
           memoisedOptions?.sequenceSplitKey,
           memoisedOptions?.useKey,
           memoisedOptions?.description,
+          memoisedOptions?.includeModifiersInKeys,
         )
 
         if (hotkey.isSequence) {
@@ -215,6 +216,7 @@ export default function useHotkeys<T extends HTMLElement>(
             memoisedOptions?.sequenceSplitKey,
             memoisedOptions?.useKey,
             memoisedOptions?.description,
+            memoisedOptions?.includeModifiersInKeys,
           ),
         ),
       )
@@ -235,6 +237,7 @@ export default function useHotkeys<T extends HTMLElement>(
               memoisedOptions?.sequenceSplitKey,
               memoisedOptions?.useKey,
               memoisedOptions?.description,
+              memoisedOptions?.includeModifiersInKeys,
             ),
           ),
         )

packages/react-hotkeys-hook/src/test/useHotkeys.test.tsx

@@ -1650,4 +1650,17 @@ test('Should trigger only produced key hotkeys', async () => {
   await user.keyboard('Y')
   expect(callbackZ).toHaveBeenCalledTimes(1)
   expect(callbackY).toHaveBeenCalledTimes(2)
-})
+})
+
+test('Should allow passing through modifier keys in keys array', async () => {
+  const user = userEvent.setup()
+
+  const callbackZ = vi.fn()
+
+  renderHook(() => useHotkeys(['ctrl+alt+z'], (_, {keys}) => {
+    callbackZ(keys)
+  }, {useKey: true, includeModifiersInKeys: true}))
+
+  await user.keyboard('{Control>}{Alt>}z{/Alt}{/Control}')
+  expect(callbackZ).toHaveBeenCalledWith(['ctrl', 'alt', 'z'])
+})