ansi-escapes

> ANSI escape codes for manipulating the terminal

Install

``sh
npm install ansi-escapes
`

Usage

`js
import ansiEscapes from 'ansi-escapes';

// Moves the cursor two rows up and to the left
process.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
//=> '\u001B[2A\u001B[1000D'
`

Or use named exports...

`js
import {cursorUp, cursorLeft} from 'ansi-escapes';

// etc, as above...
`

You can also use it in the browser with Xterm.js:

`js
import ansiEscapes from 'ansi-escapes';
import {Terminal} from 'xterm';
import 'xterm/css/xterm.css';

const terminal = new Terminal({…});

// Moves the cursor two rows up and to the left
terminal.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
//=> '\u001B[2A\u001B[1000D'
`

API

$3

Set the absolute position of the cursor. x0 y0 is the top left of the screen.

$3

Set the position of the cursor relative to its current position.

$3

Move cursor up a specific amount of rows. Default is 1.

$3

Move cursor down a specific amount of rows. Default is 1.

$3

Move cursor forward a specific amount of columns. Default is 1.

$3

Move cursor backward a specific amount of columns. Default is 1.

$3

Move cursor to the left side.

$3

Save cursor position.

$3

Restore saved cursor position.

$3

Get cursor position.

$3

Move cursor to the next line.

$3

Move cursor to the previous line.

$3

Hide cursor.

$3

Show cursor.

$3

Erase from the current cursor position up the specified amount of rows.

$3

Erase from the current cursor position to the end of the current line.

$3

Erase from the current cursor position to the start of the current line.

$3

Erase the entire current line.

$3

Erase the screen from the current line down to the bottom of the screen.

$3

Erase the screen from the current line up to the top of the screen.

$3

Erase the screen and move the cursor the top left position.

$3

Scroll display up one line.

$3

Scroll display down one line.

$3

Clear only the visible terminal screen (viewport) without affecting scrollback buffer or terminal state.

This is a safer alternative to clearScreen that works consistently across terminals.

$3

Clear the terminal screen.

> [!WARNING]
> This uses RIS (Reset to Initial State) which may also clear scrollback buffer in some terminals (xterm.js, VTE) and reset terminal modes. Consider using clearViewport() for safer viewport-only clearing.

$3

Clear the whole terminal, including scrollback buffer. (Not just the visible part of it)

$3

Enter the alternative screen.

$3

Exit the alternative screen, assuming enterAlternativeScreen was called before.

$3

Begin synchronized output to reduce flicker during renders.

$3

End synchronized output.

$3

Wrap output in synchronized output sequences to reduce flicker during renders.

$3

Output a beeping sound.

$3

Create a clickable link.

Supported terminals. Use supports-hyperlinks to detect link support.

$3

Display an image.

See term-img for a higher-level module.

#### input

Type: Buffer

Buffer of an image. Usually read in with fs.readFile().

#### options

Type: object

##### width
##### height

Type: string | number

The width and height are given as a number followed by a unit, or the word "auto".

- N: N character cells.
- Npx: N pixels.
- N%: N percent of the session's width or height.
- auto: The image's inherent size will be used to determine an appropriate dimension.

##### preserveAspectRatio

Type: boolean\
Default: true

$3

Type: string\
Default: process.cwd()

Set the current working directory for both iTerm2 and ConEmu.

$3

Type: string\
Default: process.cwd()

Inform iTerm2 of the current directory to help semantic history and enable Cmd-clicking relative paths.

$3

Type: string\
Default: process.cwd()

Inform ConEmu about shell current working directory.

$3

Creates an escape code to display an "annotation" in iTerm2.

An annotation looks like this when shown:

See the iTerm Proprietary Escape Codes documentation for more information.

#### message

Type: string

The message to display within the annotation.

The | character is disallowed and will be stripped.

#### options

Type: object

##### length

Type: number\
Default: The remainder of the line

Nonzero number of columns to annotate.

##### x

Type: number\
Default: Cursor position

Starting X coordinate.

Must be used with y and length.

##### y

Type: number\
Default: Cursor position

Starting Y coordinate.

Must be used with x and length.

##### isHidden

Type: boolean\
Default: false`

Create a "hidden" annotation.

Annotations created this way can be shown using the "Show Annotations" iTerm command.

Related

- ansi-styles - ANSI escape codes for styling strings in the terminal