Node.js Reference ยท Streams and readline
Node.js readline.cursorTo(), moveCursor() and clearLine()
Reference for readline.cursorTo(), moveCursor(), clearLine() and clearScreenDown(): the escape codes they write, return values, and how to draw a progress bar.
Four small functions in node:readline control the cursor on a terminal: cursorTo() jumps to a column (and optionally a row), moveCursor() moves relative to where it is, clearLine() erases part or all of the current line, and clearScreenDown() erases everything below the cursor. They are how you build progress bars, spinners and status lines that rewrite themselves instead of scrolling.
Each function takes the output stream as its first argument and writes an ANSI escape sequence to it. They do not check that the stream is a terminal, so on a file or pipe you would write raw escape codes into the data. Guard terminal-only output with stream.isTTY.
import readline from "node:readline"; process.stdout.write("Loading... 10%"); readline.cursorTo(process.stdout, 0); readline.clearLine(process.stdout, 0); process.stdout.write("Loading... 20%");
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.cursorTo(stream, x, y?, callback?): boolean readline.moveCursor(stream, dx, dy, callback?): boolean readline.clearLine(stream, dir, callback?): boolean readline.clearScreenDown(stream, callback?): boolean
| Name | Description |
|---|---|
stream |
A writable stream, normally process.stdout. |
x, y |
Zero-based column and row. If y is omitted only the column changes. |
dx, dy |
Relative movement. Positive dx is right, positive dy is down. |
dir |
-1 clears to the left of the cursor, 1 to the right, 0 the entire line. |
callback |
Called once the code has been written. |
Returns: the result of stream.write(): false means the stream wants you to wait for drain, true otherwise.
Errors and edge cases:
cursorTo(stream, undefined, y)throwsERR_INVALID_CURSOR_POS, because a row cannot be set without a column.- Passing
nullorundefinedas the stream does nothing and returnstrue. - Coordinates are zero-based, but the sequences sent are one-based (
cursorTo(s, 5)writesESC[6G).
Usage notes
- The cursor functions do not clear anything on their own:
cursorTo(0)only moves; callclearLine()before writing a shorter line over a longer one, or stale characters remain. - Use
\ras a cheap alternative tocursorTo(0)when you only need a carriage return. - When output goes to a file or a CI log,
isTTYis falsy. Fall back to plain lines, as in the second example. - Windows terminals and modern Unix terminals support these sequences. Very old terminals may not.
- The
Interfacealso hasrl.getCursorPos(), and thereadline/promisesReadlineclass can queue these actions andcommit()them in a batch. - For colors use util.styleText(); for the terminal itself see the tty module.