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.
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
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.
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
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 akeypresslistener exists, and reading data in this way puts the stream in flowing mode.- A
readline.Interfacecreated onprocess.stdinwith a TTY output already calls it, sokeypressevents work there without extra setup. setRawMode()exists only on TTY streams. Checkprocess.stdin.isTTYfirst; 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.