Hotkeys

Commands

The prism-code-editor/commands entrypoint exports many editing commands. These commands receive an editor and return a boolean or void. A falsy value indicates the command doesn’t apply (most commands don’t apply in readOnly mode, for example), while true means it successfully executed.

Adding hotkeys

To bind a command to a specific key, use addEditorHotkey(). This will add the command at the end of a list of callbacks for the specified key, or at the beginning if the 4th highPrecedence parameter is set to true. When the command is executed, it gets passed the editor and KeyboardEvent as arguments.

	
import { addEditorHotkey, toggleComment } from "prism-code-editor/commads"

addEditorHotkey(editor, "mod+/", () => toggleComment(editor))

When multiple commands are registered for one key, they are ran in order until one returns true, in which case the event is considered “handled” and stopImmediatePropagation() along with preventDefault().

Debugging

Multiple different keys are usually tried when pressing punctuation keys or Shift + a number key for better compatibility across different keyboard layouts and platforms. The editor below will show all keys tried for the most recent keypress. This is useful for debugging why a command isn’t executing. For better visibility, " " has been replaced with "space".

Previous keys:

With `editorCommands` extension

The editorCommands() can be used to add commands from a keymap, such as defaultKeymap or a custom keymap if you’re dissatisfied with the default one. Note that multiple instances of editorCommands() should not be added to an editor, because it does more than just adding the hotkeys; instead, merge the keymaps or add extra commands manually with addEditorHotkey().

	
import { editorCommands, defaultKeymap } from "prism-code-editor/commands"

editor.addExtensions(editorCommands(defaultKeymap))

Hotkey syntax

Keys are strings that can appear in KeyboardEvent.key, preceded by any number of modifiers, all separated by +, such as ctrl+shift+enter. Hotkeys are case-insensitive.

Normalization

To ensure hotkeys are matched regardless of the order of modifiers, the modifiers are normalized using normalizeKey() to a bitmask according to the following list:

alt → 1
ctrl or control → 2
meta or cmd → 4
shift → 8
mod → 4 on Mac, 2 otherwise

If wanted, bitmasks can be used directly in combination with strings for modifiers. Here are some examples:

	
normalizeKey("a") // "0+a"
normalizeKey("ctrl+alt+A") // "3+a"
normalizeKey("10+ALT+a") // "11+a"
normalizeKey("shift+alt+12+a") // "13+a"

Controlling execution order

The 4th precedence parameter can be used to control the execution order when multiple hotkeys are registered to the same key. The precedence is a positive integer that defaults to 2, where lower numbers yield higher precedence. A precedence of 1 should be used when conditionally overriding existing commands. Precedence 0, (the highest) should be used with caution since it can override sequential commands if the key is included in a sequence. When commands have the same precedence, they execute in the order they were added.

Listening for any key

When adding a hotkey with "any" as the key, it will run for any keydown event, after commands for the current key even if a one returned true. Note that returning true from the command won’t mark the event as “handled”.

addEditorHotkey(editor, "any", (_editor, e, key) => {
	if (e.defaultPrevented) {
		console.log(`${key} was handled`)
	}
})

Sequential hotkeys

This library also supports adding sequential hotkeys where multiple keys must be pressed one after another to execute the command. To bind a command to a sequence, use addEditorHotkeySequence().

import { addEditorHotkeySequence } from "prism-code-editor/commads"

// VS Code-like binding
addEditorHotkeySequence(editor, ["mod+k", "mod+c"], () => {
	return addLineComment(editor)
})

Sequential options

The last, optional parameter (type HotkeySequenceOptions) configures some behavior of the sequential hotkey. The example below shows the defaults:

addEditorHotkeySequence(editor, ["mod+k", "mod+c"], command, {
	timeout: 2000, // Time in milliseconds allowed between steps
	preventDefault: true, // Whether to call preventDefault() between steps
	precedence: 2, // Precedence of the command that starts the sequence
})

How sequences work

The first key in the sequence gets bound to a command that starts the sequence. When the sequence is advanced, a hotkey for the next key in the sequence gets added until the final step, when the command gets executed instead. If another key was pressed or the timeout expired between steps, the sequence is reset. Note that pressing modifier keys like Alt or Shift won’t reset the sequence. If multiple sequences share the same steps, they will advance simultaneously.

Removing hotkeys

All functions that add hotkeys return a cleanup function to remove the hotkey.

const remove = addEditorHotkey(editor, "enter", () => {
	console.log("This will only run once!")
	remove()
})

Hotkeys outside editors

The utilities for adding and running hotkeys are exported, meaning you can easily add hotkeys to your own application with full control over where listeners are added and how events are filtered.

import {
	runHotkeys,
	HotkeyMap,
	addHotkey,
	addHotkeySequence
} from "prism-code-editor/commands"

const keyMap: HotkeyMap<undefined> = {}

addEventListener("keydown", e => {
	const target = e.target as Element

	// Filter events on text fields
	if (target.matches("input, textarea") || target.isContentEditable) {
		return
	}

	runHotkeys(e, keyMap, undefined)
})

addHotkey(keyMap, "mod+s", () => {
	console.log("Saved!")
	return true
})

addHotkeySequence(keyMap, ["g", "g"], () => {
	window.scrollTo(0, 0)
	return true
})

Matching hotkeys

The getKeysFromEvent() utility can be used to check if a key matches a keyboard event. The return values from getKeysFromEvent(e) and normalizeKey() can be cached for better performance when checking multiple hotkeys.

	
if (getKeysFromEvent(e).has(normalizeKey("mod+s"))) console.log("Saved!")

Adding input commands

Editors also have an inputCommandMap that maps user input (InputEvent.data) to functions called when that input is typed. This is used by editorCommands() to automatically close brackets, quotes, and XML tags. If the handler returns true, e.preventDefault() and e.stopImmediatePropagation() get called in the beforeinput handler.

Recording hotkeys

getKeysFromEvent() can be used to to capture shortcuts pressed by users for customizable key bindings.

import {
	getKeysFromEvent,
	normalizeKey,
	isModifierKey,
	addHotkey,
	formatHotkey
} from "prism-code-editor/commands"

const stopRecording = () => {
	removeEventListener("keydown", recordShortcut)
}

const startRecording = () => {
	addEventListener("keydown", recordShortcut)
}

const recordShortcut = (e: KeyboardEvent) => {
	// Skip presses of Ctrl, Shift, Alt, and Meta
	if (isModifierKey(e)) return

	// Grab first key from Set
	const [key] = getKeysFromEvent(e)

	if (key == normalizeKey("escape")) {
		return stopRecording()
	}

	console.log(formatHotkey(key)) // Display shortcut to user
	addHotkey(keyMap, key, () => {}) // Register hotkey
	stopRecording()
}

Displaying hotkeys

This library exports a formatHotkey() utility to format hotkeys before displaying them to users. In addition, you’ll find lists of keyboard shortcuts and descriptions for defaultKeymap, autoComplete(), and searchWidget(). The following example shows how all shortcuts can be rendered with JSX:

import {
	formatHotkey,
	defaultKeymapLabels,
	searchShortcutLabels,
	autoCompleteShortcutLabels
} from "prism-code-editor/commands"

function HotkeyList({ list }: { list: [string, string][] }) {
	return (
		<ul>
			{list.map(([key, description], i) => (
				<li key={i}>
					<span>{description}</span>
					<kbd>{formatHotkey(key)}</kbd>
				</li>
			))}
		</ul>
	)
}

function App() {
	return <>
		<h2>Code editor</h2>
		<HotkeyList list={defaultKeymapLabels} />
		<h2>Search widget</h2>
		<HotkeyList list={searchShortcutLabels} />
		<h2>Autocompletion</h2>
		<HotkeyList list={autoCompleteShortcutLabels} />
	</>
}

Example

Below you can see all shortcuts rendered in lists.