shortcutDef

Release 2.4.0+

Defines keyboard shortcuts for a custom plugin.

Top-level Keys

Name	Type	Description
`key`	object	Per-OS shortcut bindings.
`option`	object	What runs when the shortcut fires (action / function), plus other options.

`key`

Name	Type	Description
`windows`	string	Windows shortcut
`mac`	string	Mac shortcut

`option`

Name	Type	Description
`action`	string	Editor Action to run.
`params`	object	Arguments passed to the action.
`onExecute`	function	Release 2.15.2211+ Function to run. If both `action` and `onExecute` are set, only `onExecute` runs.
`focusIme`	boolean	Whether to refocus the editor after the shortcut fires (default `true`).
`override`	boolean	Release 3.2.2507+ When `true`, overrides an existing shortcut (default `false`).

Shortcut Strings

Combine keys with +. Examples:

Ctrl + Shift + ; → 'Ctrl+Shift+;'
Ctrl + Alt + N → 'Ctrl+Alt+N'

// Ctrl+Shift+;
shortcutDef: {
  key: { windows: 'Ctrl+Shift+;', mac: 'Cmd+Shift+;' },
  option: { /* ... */ }
}

// Ctrl+Alt+N
shortcutDef: {
  key: { windows: 'Ctrl+Alt+N', mac: 'Cmd+Alt+N' },
  option: { /* ... */ }
}

Supported Keys

Ctrl, Shift, Alt (Mac: Option), Cmd (Mac only), 0–9, A–Z, F1–F12, ; + , - . / ` [ \ ] ', Backspace, Tab, Enter, Esc, Space, PageUp, PageDown, End, Home, Insert, Delete, Left, Up, Right, Down.

Examples

Run an editor action

shortcutDef: {
  key: { /* ... */ },
  option: { action: 'increaseFontSize' }
}

Action with params

shortcutDef: {
  key: { /* ... */ },
  option: { action: 'align', params: ['center'] }
}

Run a function

shortcutDef: {
  key: { /* ... */ },
  option: {
    /**
     * Receives the editor instance and the keyboard event.
     * @param {SynapEditor} editor
     * @param {KeyboardEvent} keyEvent
     */
    onExecute: function (editor, keyEvent) {
      window.alert('Shortcut test!');
    }
  }
}

Override an existing shortcut

Release 3.2.2507+

Without override, attempting to register a shortcut that's already bound shows a notification and the registration is skipped:

Setting override: true replaces the existing binding.

shortcutDef: {
  key: { /* ... */ },
  option: { /* ... */ },
  override: true
}

Single vs. Multiple Shortcuts

Single

shortcutDef: {
  key: { /* ... */ },
  option: { /* ... */ }
}

Multiple

shortcutDef: [
  {
    key: { /* ... */ },
    option: { /* ... */ }
  }
  // ...
]