Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js readline.emitKeypressEvents()

Reference for readline.emitKeypressEvents(): turn a stream into a source of keypress events, read the key object, enable raw mode, and handle Ctrl+C yourself.

readline.emitKeypressEvents(stream) makes a readable stream emit keypress events: one event per key instead of one per line. Each event gives you the typed text (str) and a key object that names the key (up, return, escape, a...) and tells you whether Ctrl, Alt or Shift was held.

Terminals normally deliver input a whole line at a time, after Enter. To see single keys as they are pressed, put the terminal in raw mode with process.stdin.setRawMode(true). In raw mode Ctrl+C no longer stops the program, so you must handle it yourself.

NODE
import readline from "node:readline";

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

process.stdin.on("keypress", (str, key) => {
  if (key.ctrl && key.name === "c") process.exit();
  console.log(key.name);
});

Try it

Node.js Decode a stream of keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A tiny menu driven by keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
readline.emitKeypressEvents(stream: Readable, interface?: readline.Interface): void
stream.on("keypress", (str: string | undefined, key: Key) => void)

interface Key {
  sequence: string;
  name?: string;
  ctrl: boolean;
  meta: boolean;
  shift: boolean;
  code?: string;
}
Name Description
stream The readable stream whose data is decoded into key events.
interface Optional readline.Interface that works with the same stream; rarely needed.
str The character typed, or undefined for keys with no text (arrows, function keys).
key.sequence The raw bytes the terminal sent.
key.name A readable name such as up, return, escape, backspace, f5 or a letter.
key.ctrl, key.meta, key.shift Which modifiers were held. meta is Alt on most terminals.

Returns: nothing; it only attaches the decoder.

Edge cases: calling it again on the same stream is harmless, because the decoder is installed only once. Uppercase letters have shift: true.

Usage notes

  • emitKeypressEvents() starts decoding as soon as a keypress listener exists, and reading data in this way puts the stream in flowing mode.
  • A readline.Interface created on process.stdin with a TTY output already calls it, so keypress events work there without extra setup.
  • setRawMode() exists only on TTY streams. Check process.stdin.isTTY first; piped input has no raw mode.
  • In raw mode you own Ctrl+C and Ctrl+D. Always provide an exit, and reset with setRawMode(false) before quitting so the shell is not left in a broken state.
  • A lone Escape key is ambiguous with the start of a longer sequence, so its event can arrive after a short delay.
  • The decoder understands common xterm and Windows console sequences, not every terminal in existence.