Skip to main content

KeyboardShortcutsManager

from v9.3

KeyboardShortcutsManager installs keyboard shortcuts on an event source that forwards DOM keydown events.

Usage​

Use KeyboardShortcutsManager when your application already has an event manager that forwards keyboard events.

import {
  KeyboardShortcutsManager,
  type KeyboardShortcut
} from '@deck.gl-community/panels';

const shortcuts: KeyboardShortcut[] = [
  {
    key: '/',
    commandKey: true,
    name: 'Show shortcuts',
    description: 'Open keyboard shortcuts',
    preventDefault: true,
    onKeyPress: () => setOpen(true)
  }
];

const manager = new KeyboardShortcutsManager(eventManager, shortcuts);
manager.start();

Use KeyboardShortcutsManagerDocument when shortcuts should be installed directly on document.

import {
  KeyboardShortcutsManagerDocument,
  type KeyboardShortcut
} from '@deck.gl-community/panels';

const shortcuts: KeyboardShortcut[] = [
  {
    key: 'Escape',
    name: 'Close',
    description: 'Close the active panel',
    onKeyPress: () => setOpen(false)
  }
];

const manager = new KeyboardShortcutsManagerDocument(shortcuts);
manager.start();

Types​

type KeyboardShortcutManagerEvent = {
  srcEvent: KeyboardEvent;
};

type KeyboardShortcutEventManager = {
  on(event: 'keydown', handler: (event: KeyboardShortcutManagerEvent) => void): void;
  off(event: 'keydown', handler: (event: KeyboardShortcutManagerEvent) => void): void;
};

type KeyboardShortcutDisplayPair = {
  id: string;
  position: 'primary' | 'secondary';
  description: string;
};

type KeyboardShortcut = {
  key: string;
  name: string;
  description: string;
  onKeyPress?: () => void;
  commandKey?: boolean;
  ctrlKey?: boolean;
  shiftKey?: boolean;
  dragMouse?: boolean;
  badges?: string[];
  preventDefault?: boolean;
  displayInputs?: ShortcutDisplayInput[];
  displaySection?: 'navigation' | 'interaction' | 'commands' | 'settings';
  displayPair?: KeyboardShortcutDisplayPair;
};

Methods​

start(): void;
stop(): void;

Remarks​

  • KeyboardShortcutsManager works with any event manager that implements the on('keydown', ...) and off('keydown', ...) contract.
  • KeyboardShortcutsManagerDocument is the simplest option for stand-alone DOM usage.
  • Both managers dispatch onKeyPress on the most specific matching KeyboardShortcut.
  • Shortcut matching is exact for modifiers: extra command, control, shift, or alt modifiers do not trigger shortcuts unless the shortcut explicitly matches them. Alt-key shortcuts are reserved for future support.
  • Set preventDefault on a shortcut to prevent the browser default behavior after it matches.
  • Shortcut matching is shared with KeyboardShortcutsPanel and the exported keyboard shortcut helpers.