Use Hotkeys

import { UseHotkeysDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.useHotkeys);

Usage

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

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

The second argument is a list of HTML tags on which hotkeys should be ignored. By default, hotkey events are ignored if the focus is in input, textarea, and select elements.

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

function Demo() {
  // Ignore hotkey events only when focus is in input and textarea elements
  useHotkeys(
    [['ctrl+K', () => console.log('Trigger search')]],
    ['INPUT', 'TEXTAREA']
  );

  // Empty array – do not ignore hotkey events on any element
  useHotkeys([['ctrl+K', () => console.log('Trigger search')]], []);
}

Targeting elements

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

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
• shift + [plus] – you can use [plus] to detect + key
• Digit1 and Hotkey1 - you can use physical key assignments defined on MDN.

Types

The @mantine/hooks package exports HotkeyItemOptions and HotkeyItem types:

interface HotkeyItemOptions {
  preventDefault?: boolean;
  usePhysicalKeys?: boolean;
}

type HotkeyItem = [
  string,
  (event: KeyboardEvent) => void,
  HotkeyItemOptions?,
];

HotkeyItemOptions provides the usePhysicalKeys option to force physical key assignment. This is useful for non-QWERTY keyboard layouts.

The HotkeyItem type can be used to create hotkey items outside of the use-hotkeys hook:

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

const hotkeys: HotkeyItem[] = [
  [
    'mod+J',
    () => console.log('Toggle color scheme'),
    { preventDefault: false },
  ],
  ['ctrl+K', () => console.log('Trigger search')],
  ['alt+mod+shift+X', () => console.log('Rick roll')],
  [
    'D',
    () => console.log('Triggers when pressing "E" on Dvorak keyboards!'),
    { usePhysicalKeys: true }
  ],
];

useHotkeys(hotkeys);

Definition

interface HotkeyItemOptions {
  preventDefault?: boolean;
  usePhysicalKeys?: boolean;
}

type HotkeyItem = [string, (event: KeyboardEvent) => void, HotkeyItemOptions?]

function useHotkeys(
  hotkeys: HotkeyItem[],
  tagsToIgnore?: string[],
  triggerOnContentEditable?: boolean
): void;

Exported types

The HotkeyItemOptions and HotkeyItem types are exported from @mantine/hooks;

import type { HotkeyItemOptions, HotkeyItem } from '@mantine/hooks';