Skip to main content
This page documents all the TypeScript types exported by react-hotkeys-hook.

​
Core Types

​
Keys

Represents a hotkey string or array of hotkey strings. 
type Keys = string | readonly string[]
Examples: 
// Single hotkey
const key: Keys = 'ctrl+k'

// Multiple hotkeys
const keys: Keys = ['ctrl+k', 'cmd+k']

​
Scopes

Represents a scope or array of scopes for organizing hotkeys. 
type Scopes = string | readonly string[]
Examples: 
// Single scope
const scope: Scopes = 'modal'

// Multiple scopes
const scopes: Scopes = ['modal', 'dialog', 'overlay']

​
HotkeyCallback

The callback function type that gets called when a hotkey is triggered. 
type HotkeyCallback = (
  keyboardEvent: KeyboardEvent,
  hotkeysEvent: HotkeysEvent
) => void
Parameters:
  • keyboardEvent - The native browser KeyboardEvent
  • hotkeysEvent - Enhanced event with hotkey information
Examples: 
const handleSearch: HotkeyCallback = (keyboardEvent, hotkeysEvent) => {
  console.log('Key pressed:', keyboardEvent.key)
  console.log('Hotkey matched:', hotkeysEvent.hotkey)
  console.log('Description:', hotkeysEvent.description)
}

useHotkeys('ctrl+k', handleSearch)

​
HotkeysEvent

The enhanced event object passed to the callback containing hotkey information. 
type HotkeysEvent = Hotkey
Properties:
​
hotkey
string
required
The matched hotkey string (e.g., ‘ctrl+k’)
​
keys
readonly string[]
Array of individual keys in the hotkey
​
scopes
Scopes
The scope(s) this hotkey belongs to
​
description
string
Description of what the hotkey does
​
isSequence
boolean
Whether this is a sequence hotkey (e.g., ‘g>i’)
​
metadata
Record<string, unknown>
Custom metadata associated with the hotkey
​
alt
boolean
Whether the Alt/Option key was pressed
​
ctrl
boolean
Whether the Control key was pressed
​
meta
boolean
Whether the Meta/Command key was pressed
​
shift
boolean
Whether the Shift key was pressed
​
mod
boolean
Whether the modifier key (Cmd on Mac, Ctrl on Windows/Linux) was pressed
​
useKey
boolean
Whether the hotkey uses the key instead of code
Examples: 
useHotkeys('ctrl+k', (event, hotkeysEvent) => {
  console.log(hotkeysEvent.hotkey)      // 'ctrl+k'
  console.log(hotkeysEvent.ctrl)        // true
  console.log(hotkeysEvent.keys)        // ['ctrl', 'k']
  console.log(hotkeysEvent.description) // 'Open search'
  console.log(hotkeysEvent.metadata)    // { category: 'navigation' }
}, {
  description: 'Open search',
  metadata: { category: 'navigation' }
})

​
Modifier Types

​
KeyboardModifiers

Represents modifier keys that can be combined with regular keys. 
type KeyboardModifiers = {
  alt?: boolean
  ctrl?: boolean
  meta?: boolean
  shift?: boolean
  mod?: boolean
  useKey?: boolean
}
Properties:
​
alt
boolean
Alt key on Windows/Linux, Option key on Mac
​
ctrl
boolean
Control key
​
meta
boolean
Meta key on Windows/Linux, Command key on Mac
​
shift
boolean
Shift key
​
mod
boolean
Platform-specific modifier: Cmd on Mac, Ctrl on Windows/Linux
​
useKey
boolean
Custom modifier to listen to the produced key instead of the code
Examples: 
// Ctrl+K on Windows/Linux, Cmd+K on Mac
useHotkeys('mod+k', handleSearch)

// Shift+Alt+T
useHotkeys('shift+alt+t', handleNewTab)

// Using the key instead of code
useHotkeys('z', handleUndo, { useKey: true })

​
Form and Element Types

​
FormTags

HTML form element tags and ARIA roles where hotkeys can be enabled. 
type FormTags =
  | 'input'
  | 'textarea'
  | 'select'
  | 'INPUT'
  | 'TEXTAREA'
  | 'SELECT'
  | 'searchbox'
  | 'slider'
  | 'spinbutton'
  | 'menuitem'
  | 'menuitemcheckbox'
  | 'menuitemradio'
  | 'option'
  | 'radio'
  | 'textbox'
Examples: 
// Enable on all input and textarea elements
useHotkeys('ctrl+s', handleSave, {
  enableOnFormTags: ['input', 'textarea']
})

// Enable on ARIA roles
useHotkeys('enter', handleSelect, {
  enableOnFormTags: ['menuitem', 'option']
})

​
Function Types

​
Trigger

A boolean or function that determines whether a hotkey should be triggered. 
type Trigger = boolean | (
  (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean
)
Examples: 
// Simple boolean
useHotkeys('ctrl+k', handleSearch, {
  enabled: true
})

// Function based trigger
useHotkeys('ctrl+k', handleSearch, {
  enabled: (event, hotkeysEvent) => {
    return !event.shiftKey
  }
})

// Conditional preventDefault
useHotkeys('ctrl+s', handleSave, {
  preventDefault: (event, hotkeysEvent) => {
    // Only prevent default for ctrl+s, not ctrl+shift+s
    return !event.shiftKey
  }
})

​
Configuration Types

​
EventListenerOptions

Options passed to the underlying event listener. 
type EventListenerOptions =
  | {
      capture?: boolean
      once?: boolean
      passive?: boolean
      signal?: AbortSignal
    }
  | boolean // useCapture
Properties:
​
capture
boolean
If true, the event listener will be triggered during the capture phase
​
once
boolean
If true, the listener will be automatically removed after being called once
​
passive
boolean
If true, indicates that the listener will never call preventDefault()
​
signal
AbortSignal
An AbortSignal to remove the event listener
Examples: 
const controller = new AbortController()

useHotkeys('ctrl+k', handleSearch, {
  eventListenerOptions: {
    capture: true,
    passive: false,
    signal: controller.signal
  }
})

// Later: remove the listener
controller.abort()

​
Options

The main configuration object for customizing hotkey behavior. See the Options page for detailed documentation. 
type Options = {
  enabled?: Trigger
  enableOnFormTags?: readonly FormTags[] | boolean
  enableOnContentEditable?: boolean
  ignoreEventWhen?: (e: KeyboardEvent) => boolean
  splitKey?: string
  delimiter?: string
  scopes?: Scopes
  keyup?: boolean
  keydown?: boolean
  preventDefault?: Trigger
  description?: string
  document?: Document
  ignoreModifiers?: boolean
  eventListenerOptions?: EventListenerOptions
  useKey?: boolean
  sequenceTimeoutMs?: number
  sequenceSplitKey?: string
  metadata?: Record<string, unknown>
}

​
OptionsOrDependencyArray

Union type used internally for the third parameter of useHotkeys. 
import type { DependencyList } from 'react'

type OptionsOrDependencyArray = Options | DependencyList
Examples: 
// With options
useHotkeys('ctrl+k', handleSearch, { enabled: true })

// With dependency array
useHotkeys('ctrl+k', handleSearch, [searchQuery])

// With both (options as third param, deps as fourth)
useHotkeys('ctrl+k', handleSearch, { enabled: true }, [searchQuery])

​
Usage Examples

​
Type-Safe Callbacks

import type { HotkeyCallback, HotkeysEvent } from 'react-hotkeys-hook'
import { useHotkeys } from 'react-hotkeys-hook'

function SearchComponent() {
  const handleSearch: HotkeyCallback = (event, hotkeysEvent) => {
    // TypeScript knows the shape of both parameters
    console.log('Native event:', event.key)
    console.log('Hotkey info:', hotkeysEvent.hotkey)
    console.log('Was ctrl pressed?', hotkeysEvent.ctrl)
  }

  useHotkeys('ctrl+k', handleSearch)

  return <div>Press Ctrl+K to search</div>
}

​
Custom Trigger Functions

import type { Trigger } from 'react-hotkeys-hook'
import { useHotkeys } from 'react-hotkeys-hook'

function ConditionalHotkey() {
  const [isEnabled, setIsEnabled] = useState(true)

  const shouldTrigger: Trigger = (event, hotkeysEvent) => {
    // Complex condition
    return isEnabled && !event.shiftKey && hotkeysEvent.ctrl
  }

  useHotkeys('ctrl+k', handleAction, {
    enabled: shouldTrigger,
    preventDefault: shouldTrigger
  })

  return <button onClick={() => setIsEnabled(!isEnabled)}>Toggle</button>
}

​
Working with Metadata

import { useHotkeys } from 'react-hotkeys-hook'
import type { HotkeysEvent } from 'react-hotkeys-hook'

interface MyMetadata {
  category: string
  priority: 'low' | 'medium' | 'high'
  analytics?: {
    event: string
    properties: Record<string, unknown>
  }
}

function App() {
  const handleHotkey = (event: KeyboardEvent, hotkeysEvent: HotkeysEvent) => {
    const metadata = hotkeysEvent.metadata as MyMetadata
    
    if (metadata?.analytics) {
      trackEvent(metadata.analytics.event, metadata.analytics.properties)
    }
  }

  useHotkeys('ctrl+k', handleHotkey, {
    metadata: {
      category: 'navigation',
      priority: 'high',
      analytics: {
        event: 'search_opened',
        properties: { source: 'keyboard' }
      }
    } as MyMetadata
  })

  return <div>App</div>
}

Build docs developers (and LLMs) love

Get started for freeTalk to us