ansi-escapes 7.x

Complete instructions

Verified against ansi-escapes@7.3.0 on 2026-09-08. 5 of 5 examples executed.

ansi-escapes 7.x

Runtime and module shape

ansi-escapes@^7.0.0 is ESM-only in practice. Use Node.js 18 or newer and import it with import, not require(). The package has no CLI or runtime runner: its APIs return strings, which the caller writes to a terminal or terminal emulator.

Both import styles are supported:

import assert from 'node:assert/strict';
import ansiEscapes, {cursorUp, cursorLeft} from 'ansi-escapes';

assert.equal(ansiEscapes.cursorUp(2), '\u001B[2A');
assert.equal(cursorUp(2) + cursorLeft, '\u001B[2A\u001B[G');
assert.equal(ansiEscapes.cursorLeft, cursorLeft);

The older major's default-object usage remains valid, but version 7 also exports the declarations as named exports. Do not assume the 6.x package metadata: version 7 requires Node >=18, is ESM-only, and exposes ./index.js together with its declarations.

Cursor movement and position

Available cursor APIs are:

• cursorTo(x, y?)
• cursorMove(x, y?)
• cursorUp(count)
• cursorDown(count)
• cursorForward(count)
• cursorBackward(count)

Cursor constants are cursorLeft, cursorSavePosition, cursorRestorePosition, cursorGetPosition, cursorNextLine, cursorPrevLine, cursorHide, and cursorShow.

All of these produce strings. Combine them and write the result yourself; the package does not move the cursor directly. cursorMove(x, y?) emits the horizontal movement before the vertical movement when both components are present.

import assert from 'node:assert/strict';
import {
  cursorTo,
  cursorMove,
  cursorUp,
  cursorDown,
  cursorForward,
  cursorBackward,
  cursorLeft,
  cursorSavePosition,
  cursorRestorePosition,
  cursorGetPosition,
  cursorNextLine,
  cursorPrevLine,
  cursorHide,
  cursorShow,
} from 'ansi-escapes';

assert.equal(cursorTo(4), '\u001B[5G');
assert.equal(cursorTo(4, 2), '\u001B[3;5H');
assert.equal(cursorMove(2, -3), '\u001B[2C\u001B[3A');
assert.equal(cursorUp(2), '\u001B[2A');
assert.equal(cursorDown(2), '\u001B[2B');
assert.equal(cursorForward(2), '\u001B[2C');
assert.equal(cursorBackward(2), '\u001B[2D');

for (const value of [
  cursorLeft,
  cursorSavePosition,
  cursorRestorePosition,
  cursorGetPosition,
  cursorNextLine,
  cursorPrevLine,
  cursorHide,
  cursorShow,
]) {
  assert.equal(typeof value, 'string');
}

Do not copy the older example that expects cursorLeft to be \u001B[1000D; version 7 produces a cursor-left escape represented as \u001B[G.

Erasing, scrolling, and screen control

The line and screen exports are:

• eraseLines(count)
• eraseEndLine, eraseStartLine, eraseLine
• eraseDown, eraseUp, eraseScreen
• scrollUp, scrollDown
• clearScreen, clearTerminal
• enterAlternativeScreen, exitAlternativeScreen
• beep

Use eraseLines(count) when the number of lines is dynamic. The other names are string constants.

import assert from 'node:assert/strict';
import ansiEscapes, {
  eraseLines,
  eraseEndLine,
  eraseStartLine,
  eraseLine,
  eraseDown,
  eraseUp,
  eraseScreen,
  scrollUp,
  scrollDown,
  clearScreen,
  clearTerminal,
  enterAlternativeScreen,
  exitAlternativeScreen,
  beep,
} from 'ansi-escapes';

assert.equal(typeof eraseLines(3), 'string');
for (const value of [
  eraseEndLine,
  eraseStartLine,
  eraseLine,
  eraseDown,
  eraseUp,
  eraseScreen,
  scrollUp,
  scrollDown,
  clearScreen,
  clearTerminal,
  enterAlternativeScreen,
  exitAlternativeScreen,
  beep,
]) {
  assert.equal(typeof value, 'string');
}

assert.equal(typeof ansiEscapes.clearTerminal, 'string');

Hyperlinks, images, and iTerm2 features

link(text, url) returns a terminal hyperlink escape sequence. Terminal support is provided by the terminal emulator, not by this package.

image(data, options?) returns an image escape sequence. The input is a Uint8Array; in Node, a Buffer is also a Uint8Array. Image options are optional, and preserveAspectRatio defaults to true.

The iTerm namespace provides iTerm.setCwd(path?) and iTerm.annotation(message, options?). These sequences are intended for iTerm2; generating them does not make another terminal support them.

import assert from 'node:assert/strict';
import ansiEscapes, {link, image, iTerm} from 'ansi-escapes';

const hyperlink = link('Click here', 'https://example.com');
assert.equal(typeof hyperlink, 'string');
assert.ok(hyperlink.includes('Click here'));
assert.ok(hyperlink.includes('https://example.com'));

const imageSequence = image(new Uint8Array([0, 1, 2, 3]));
assert.equal(typeof imageSequence, 'string');
assert.ok(imageSequence.length > 0);

const cwdSequence = iTerm.setCwd('/tmp');
assert.equal(typeof cwdSequence, 'string');
assert.ok(cwdSequence.length > 0);

const annotationSequence = iTerm.annotation('build complete');
assert.equal(typeof annotationSequence, 'string');
assert.ok(annotationSequence.length > 0);

assert.equal(typeof ansiEscapes.link, 'function');

Writing the result

The package only creates escape-code strings. Write them to an output stream or pass them to a terminal implementation:

import assert from 'node:assert/strict';
import ansiEscapes from 'ansi-escapes';

let output = '';
output += ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft;
assert.equal(output, '\u001B[2A\u001B[G');

Do not expect importing the package to alter the terminal, and do not wrap examples in describe, it, or expect; those are runner globals and are not available in a directly executed script.

Not covered

This skill does not cover terminal-by-terminal compatibility, the complete option shapes for image or iTerm annotations, the exact escape encoding of every export, browser integration, or how to read image data from a filesystem. It also does not cover a CLI or runner because ansi-escapes exposes no documented CLI or runtime runner.