use-hotkeys

Usage

use-hotkeys accepts as its first argument an array of hotkeys and handler tuples:

• hotkey - hotkey string, for example ctrl+E, shift+alt+L, mod+S
• handler - event handler called when a given combination was pressed
• options - object with extra options for hotkey handler

The second argument is a list of HTML tags:

• tagsToIgnore - HTML tag names that hotkeys will not trigger on
• triggerOnContentEditable - Whether shortcuts should trigger when based on contentEditable

import { useHotkeys } from '@mantine/hooks';

function Demo() {
  // ctrl + J and ⌘ + J to toggle color scheme
  // ctrl + K and ⌘ + K to search
  useHotkeys([
    ['mod+J', () => console.log('Toggle color scheme')],
    ['ctrl+K', () => console.log('Trigger search')],
    ['alt+mod+shift+X', () => console.log('Rick roll')],
  ]);

  return null;
}

Targeting elements

use-hotkeys hook can work only with document element, you will need to create your own event listener if you need to support other elements. For this purpose, @mantine/hooks package exports getHotkeyHandler function which should be used with onKeyDown:

import { useState } from 'react';
import { getHotkeyHandler } from '@mantine/hooks';
import { notifications } from '@mantine/notifications';
import { TextInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState("I've just used a hotkey to send a message");
  const handleSubmit = () => notifications.show({ title: 'Your message', message: value });
  const handleSave = () => notifications.show({ title: 'You saved', color: 'teal', message: value });

  return (
    <TextInput
      placeholder="Your message"
      label="Press ⌘+Enter or Ctrl+Enter when input has focus to send message"
      value={value}
      onChange={(event) => setValue(event.target.value)}
      onKeyDown={getHotkeyHandler([
        ['mod+Enter', handleSubmit],
        ['mod+S', handleSave],
      ])}
    />
  );
}

With getHotkeyHandler you can also add events to any dom node using .addEventListener:

import { getHotkeyHandler } from '@mantine/hooks';

document.body.addEventListener(
  'keydown',
  getHotkeyHandler([
    ['mod+Enter', () => console.log('Submit')],
    ['mod+S', () => console.log('Save')],
  ])
);

Supported formats

• mod+S – detects ⌘+S on macOS and Ctrl+S on Windows
• ctrl+shift+X – handles multiple modifiers
• alt + shift + L – you can use whitespace inside hotkey
• ArrowLeft – you can use special keys using this format

Definition

function useHotkeys(
  hotKeyItem: Array<
    [
      hotkey: string,
      handler: (event: KeyboardEvent) => void,
      options?: { preventDefault?: boolean }
    ]
  >,
  tagsToIgnore?: string[]
): void;