Skip to main content
Version: 5.0

Working with Keyboard Layouts

Keyboard shortcuts behave differently depending on the user's keyboard layout. By default, react-hotkeys-hook listens to the physical key code — not the character produced by that key.

If you want to listen for a special character like !, :, or %, you have two approaches.

Option 1 — Listen to the physical key (layout-independent)​

This is the default behavior. The hook listens to which physical keys are pressed, not the resulting character. For example, to respond to the ! character on a US layout, you listen to the physical keys that produce it:

Live Editor
function ExampleComponent() {
  const [count, setCount] = useState(0)
  useHotkeys('shift+1', () => setCount(prevCount => prevCount + 1))

  return (
    <span>Pressed the '!' key {count} times.</span>
  )
}
Result
Loading...

This is layout-independent: the same physical keystroke (shift+1) works for all users, even if their layout produces a different character. The trade-off is that you must communicate the physical shortcut (shift+1) to users, not the character (!), because you cannot guarantee that shift+1 produces ! on every layout.

Option 2 — Listen to the produced character (layout-dependent)​

If you care about the character itself rather than how it is typed, use the useKey option. This listens to the produced key instead of the physical key code:

Live Editor
function ExampleComponent() {
  const [count, setCount] = useState(0)
  useHotkeys('!', () => setCount(prevCount => prevCount + 1), { useKey: true })

  return (
    <span>Pressed the '!' key {count} times.</span>
  )
}
Result
Loading...

Now the hotkey only triggers when the user produces the ! character, regardless of which physical keys they press. On a standard US keyboard, shift+1 and ! are equivalent, but on other layouts they may differ. Choose useKey: true when the character matters more than the physical keystroke.