Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js See the escape codes

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 progress bar that only redraws on a terminal

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.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) throws ERR_INVALID_CURSOR_POS, because a row cannot be set without a column.
  • Passing null or undefined as the stream does nothing and returns true.
  • Coordinates are zero-based, but the sequences sent are one-based (cursorTo(s, 5) writes ESC[6G).

Usage notes

  • The cursor functions do not clear anything on their own: cursorTo(0) only moves; call clearLine() before writing a shorter line over a longer one, or stale characters remain.
  • Use \r as a cheap alternative to cursorTo(0) when you only need a carriage return.
  • When output goes to a file or a CI log, isTTY is 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 Interface also has rl.getCursorPos(), and the readline/promises Readline class can queue these actions and commit() them in a batch.
  • For colors use util.styleText(); for the terminal itself see the tty module.