tty-events

tty-events

tty-events is a package for handling events from the terminal, made for interactive, terminal-based applications.

Features

• Full mouse and highlight tracking support (VT200 and SGR extended);
• Bracketed paste mode support;
• Focus support;
• Full UTF-8 support;
• Support for more key combinations (especially in Windows) when compared to node:readline’s keypress event;
• Easy comparison (e.g. key == "Ctrl+s");
• unknownSequence event.

Usage Examples

Keyboard

This script logs all key presses:

if (process.stdin.isTTY)
	process.stdin.setRawMode(true);

const term = new (require("tty-events"));

term.on("keypress", (key)=>{
	console.log("You pressed %s.", key.toString());
	if (key == "Ctrl+c") {
		term.pause(); // Exit the program
	}
});

Mouse

tty-events supports mouse (VT200 and SGR extended). In order to receive mouse events, the enableMouse() function must be called first.

term.enableMouse();

term.on("mousedown", (ev)=>{
	console.log("You clicked at (%i, %i) with the button no. %i.", ev.x, ev.y, ev.button);
});

For a highlight tracking example, see the example highlight tracking script.

Pasting

tty-events supports bracketed paste mode. This feature allows to distinguish between real keystrokes and pasted text from the clipboard. This is useful in applications where certain keys trigger some command. In order to receive paste events, the enableBPM() function must be called first.

term.enableBPM();

term.on("paste", (text)=>{
	console.log("You pasted %O.", text);
});

Focus

Focus events allow an application to stop updating the screen when it's not necessary. In order to receive focus events, the enableFocus() function must be called first.

term.enableFocus();

term.on("focusin", ()=>{
	console.log("The terminal received focus.");
});
term.on("focusout", ()=>{
	console.log("The terminal lost focus.");
});

Important Notes and Limitations

Because of the way terminals work, there are some aspects that might seem unintuitive.

Uppercase VS Shift

An uppercase letter emits an event with the uppercase letter and with the shift property set to false. This is because there is no way to know if Shift was being pressed (an uppercase letter can be produced with Caps Lock). For example: Shift+Alt+A emits Alt+A instead of Alt+Shift+a.

“Twin” Keys

Some key combinations produce the same output to stdin. Here is a list of the key combinations that may not work as expected:

• Ctrl+Shift+<letter>: Emits Ctrl+<letter> (in lowercase). (The Shift modifier is ignored.)
• Ctrl+H: Emits backspace. (Terminals send \b when Ctrl+H is pressed.)
• Ctrl+I: Emits tab. (Terminals send \t when Ctrl+I is pressed.)
• Ctrl+J: Emits enter. (Terminals send \n when Ctrl+J is pressed.)
• Ctrl+M: Emits enter. (Terminals send \r when Ctrl+M is pressed.)
• Ctrl+[: Emits escape. (Terminals send \x1B when Ctrl+[ is pressed.)
• Shift+F1: Emits f11 in some terminals.
• Shift+F2: Emits f12 in some terminals.

Escape Key

Listening for Esc (escape) is discouraged. Terminals send \x1B when Esc is pressed, which is the first byte of escape sequences, and this makes the detection unreliable.

Incompatible Terminals

Also, some features and/or key combinations don't work in some terminal emulators:

• Mouse support isn't available in Windows Console.
• Bracketed paste mode isn't available in Windows Console.
• Ctrl+@ doesn't work in Windows Console and in some keyboard layouts Ctrl+\, Ctrl+], Ctrl+^ and Ctrl+- don't work too.
• Mouse highlight tracking works in few terminals, however xterm supports it.

API Documentation

The full documentation is available here.