API Reference

Complete reference for all ANSI escape code functions organized by category.

Cursor Control

Functions for cursor positioning, movement, and styling.

cursorTo

Move cursor to absolute position.

Signature:

function cursorTo(x: number, y?: number): string;

Parameters:

x (number) - Column position (0-based)
y (number, optional) - Row position (0-based)

Returns: ANSI escape sequence string

Example:

import { cursorTo } from "@visulima/ansi";
process.stdout.write(cursorTo(10, 5)); // Move to column 10, row 5

cursorMove

Move cursor relative to current position.

Signature:

function cursorMove(x: number, y: number): string;

Parameters:

x (number) - Columns to move (positive = right, negative = left)
y (number) - Rows to move (positive = down, negative = up)

Returns: ANSI escape sequence string

cursorUp / cursorDown / cursorForward / cursorBackward

Move cursor in specific direction.

Signatures:

function cursorUp(count?: number): string;
function cursorDown(count?: number): string;
function cursorForward(count?: number): string;
function cursorBackward(count?: number): string;

Parameters:

count (number, optional) - Number of positions to move. Default: 1

Returns: ANSI escape sequence string

cursorLeft

Move cursor to leftmost position (column 0).

Signature:

const cursorLeft: string;

Example:

import { cursorLeft } from "@visulima/ansi";
process.stdout.write(cursorLeft);

cursorSave / cursorRestore

Save and restore cursor position.

Signatures:

const cursorSave: string;
const cursorRestore: string;

Example:

import { cursorSave, cursorRestore } from "@visulima/ansi";
process.stdout.write(cursorSave);
// ... do work ...
process.stdout.write(cursorRestore);

cursorHide / cursorShow

Control cursor visibility.

Signatures:

const cursorHide: string;
const cursorShow: string;

Example:

import { cursorHide, cursorShow } from "@visulima/ansi";
process.stdout.write(cursorHide);
// ... do work ...
process.stdout.write(cursorShow);

setCursorStyle

Set cursor appearance.

Signature:

function setCursorStyle(style: CursorStyle): string;

Parameters:

style (CursorStyle) - One of:
- "blinking-block"
- "steady-block"
- "blinking-underline"
- "steady-underline"
- "blinking-bar"
- "steady-bar"

Returns: ANSI escape sequence string

Example:

import { setCursorStyle } from "@visulima/ansi";
process.stdout.write(setCursorStyle("blinking-bar"));

Screen Manipulation

Functions for clearing and manipulating the screen.

clearScreen

Clear the entire screen.

Signature:

const clearScreen: string;

Example:

import { clearScreen } from "@visulima/ansi";
process.stdout.write(clearScreen);

eraseDown / eraseUp

Erase from cursor to end/start of screen.

Signatures:

const eraseDown: string;
const eraseUp: string;

eraseLine / eraseLineEnd / eraseLineStart

Erase line or part of line.

Signatures:

const eraseLine: string;
const eraseLineEnd: string;
const eraseLineStart: string;

Example:

import { eraseLine } from "@visulima/ansi";
process.stdout.write(eraseLine);
console.log("New line content");

eraseLines

Erase multiple lines.

Signature:

function eraseLines(count: number): string;

Parameters:

count (number) - Number of lines to erase

Returns: ANSI escape sequence string

clearScreenAndHomeCursor

Clear screen and move cursor to home position (0, 0).

Signature:

const clearScreenAndHomeCursor: string;

alternativeScreenOn / alternativeScreenOff

Switch between normal and alternative screen buffers.

Signatures:

const alternativeScreenOn: string;
const alternativeScreenOff: string;

Example:

import { alternativeScreenOn, alternativeScreenOff } from "@visulima/ansi";

process.stdout.write(alternativeScreenOn);
// Full-screen app here
process.stdout.write(alternativeScreenOff);

scrollUp / scrollDown

Scroll screen region.

Signatures:

function scrollUp(count?: number): string;
function scrollDown(count?: number): string;

Parameters:

count (number, optional) - Number of lines to scroll. Default: 1

Returns: ANSI escape sequence string

Hyperlinks

hyperlink

Create clickable hyperlink in terminal.

Signature:

function hyperlink(url: string, text: string, options?: HyperlinkOptions): string;

Parameters:

url (string) - URL to link to
text (string) - Display text
options (HyperlinkOptions, optional) - Additional options
- id (string, optional) - Unique ID for the link

Returns: Formatted hyperlink string

Example:

import { hyperlink } from "@visulima/ansi";

const link = hyperlink("https://github.com", "GitHub");
console.log(`Visit ${link} for more info`);

Images

image

Display image in iTerm2.

Signature:

function image(buffer: Buffer | Uint8Array, options?: ImageOptions): string;

Parameters:

buffer (Buffer | Uint8Array) - Image data
options (ImageOptions, optional) - Display options
- width (number | string, optional) - Width (pixels, percent, or "auto")
- height (number | string, optional) - Height (pixels, percent, or "auto")
- preserveAspectRatio (boolean, optional) - Preserve aspect ratio. Default: true
- inline (boolean, optional) - Display inline with text. Default: false

Returns: iTerm2 image escape sequence

Example:

import { image } from "@visulima/ansi";
import { readFileSync } from "fs";

const img = readFileSync("logo.png");
process.stdout.write(image(img, { width: "50%", height: "auto" }));

Strip ANSI

strip

Remove ANSI escape codes from string.

Signature:

function strip(text: string): string;

Parameters:

text (string) - String containing ANSI codes

Returns: String with ANSI codes removed

Example:

import { strip } from "@visulima/ansi";
import { cursorUp } from "@visulima/ansi";

const withAnsi = `Hello${cursorUp(2)} World`;
const clean = strip(withAnsi);
console.log(clean); // "Hello World"

Window Control

setWindowTitle

Set terminal window title.

Signature:

function setWindowTitle(title: string): string;

Parameters:

title (string) - Window title

Returns: ANSI escape sequence string

Example:

import { setWindowTitle } from "@visulima/ansi";
process.stdout.write(setWindowTitle("My App"));

setIconName

Set window icon name.

Signature:

function setIconName(name: string): string;

Parameters:

name (string) - Icon name

Returns: ANSI escape sequence string

setIconNameAndWindowTitle

Set both icon name and window title.

Signature:

function setIconNameAndWindowTitle(title: string): string;

Parameters:

title (string) - Title for both icon and window

Returns: ANSI escape sequence string

Window Operations

Control window state and position.

Signatures:

const minimizeWindow: string;
const maximizeWindow: string;
const raiseWindow: string;
const lowerWindow: string;
const restoreWindow: string;
const refreshWindow: string;

function moveWindow(x: number, y: number): string;
function resizeTextAreaChars(width: number, height: number): string;
function resizeTextAreaPixels(width: number, height: number): string;

Example:

import { maximizeWindow, moveWindow } from "@visulima/ansi";

process.stdout.write(maximizeWindow);
process.stdout.write(moveWindow(100, 100));

Mouse Events

Enable/Disable Mouse Tracking

Signatures:

const enableNormalMouse: string;
const disableNormalMouse: string;
const enableButtonEventMouse: string;
const disableButtonEventMouse: string;
const enableAnyEventMouse: string;
const disableAnyEventMouse: string;
const enableX10Mouse: string;
const disableX10Mouse: string;

Example:

import { enableNormalMouse, disableNormalMouse } from "@visulima/ansi";

// Enable mouse tracking
process.stdout.write(enableNormalMouse);

// ... handle mouse events ...

// Disable when done
process.stdout.write(disableNormalMouse);

Terminal Modes

setMode / resetMode

Set or reset terminal modes.

Signatures:

function setMode(mode: string): string;
function resetMode(mode: string): string;

Common Modes:

"IRM" - Insert/Replace Mode
"LNM" - Line Feed/New Line Mode
"SRM" - Send/Receive Mode
"KAM" - Keyboard Action Mode

Example:

import { setMode, resetMode } from "@visulima/ansi";

process.stdout.write(setMode("IRM"));
// ... do work in insert mode ...
process.stdout.write(resetMode("IRM"));

Set, query and reset the terminal's foreground, background and cursor colors (OSC 10/11/12, reset via OSC 110/111/112). Color strings may be X11 names ("red"), hex ("#ff0000") or XParseColor strings ("rgb:ff/00/00"). Caller-supplied colors are sanitized to prevent escape-sequence injection.

Signatures:

function setForegroundColor(color: string): string;
function setBackgroundColor(color: string): string;
function setCursorColor(color: string): string;

const requestForegroundColor: string;
const requestBackgroundColor: string;
const requestCursorColor: string;

const resetForegroundColor: string;
const resetBackgroundColor: string;
const resetCursorColor: string;

Example:

import { setBackgroundColor, resetBackgroundColor } from "@visulima/ansi/background";

process.stdout.write(setBackgroundColor("#1e1e2e"));
// ... later ...
process.stdout.write(resetBackgroundColor);

Shell Integration

Working Directory (OSC 7)

Report the shell's current working directory so terminals (iTerm2, WezTerm, …) can open new tabs in the same place.

Signature:

function notifyWorkingDirectory(host: string, ...paths: string[]): string;
const setWorkingDirectory: typeof notifyWorkingDirectory;

Example:

import { notifyWorkingDirectory } from "@visulima/ansi/cwd";

process.stdout.write(notifyWorkingDirectory("", process.cwd()));

FinalTerm Prompt Marks (OSC 133)

Mark the structure of shell output (prompt / command / output boundaries) so terminals can offer jump-to-prompt and command-status features.

Signatures:

function finalTerm(...pm: string[]): string;
function finalTermPrompt(...pm: string[]): string; // A
function finalTermCmdStart(...pm: string[]): string; // B
function finalTermCmdExecuted(...pm: string[]): string; // C
function finalTermCmdFinished(...pm: string[]): string; // D

Notifications

Trigger desktop notifications using the simple OSC 9 protocol or the extensible OSC 99 protocol. Message, payload and metadata are sanitized to prevent escape-sequence injection.

Signatures:

function notify(message: string): string; // OSC 9
function desktopNotification(payload: string, ...metadata: string[]): string; // OSC 99

Example:

import { notify } from "@visulima/ansi/notification";

process.stdout.write(notify("Build finished"));

urxvt Extensions (OSC 777)

Invoke rxvt-unicode Perl extensions.

import urxvtExtension from "@visulima/ansi/urxvt";

process.stdout.write(urxvtExtension("notify", "title", "body"));

Keypad Modes

Switch the numeric keypad between application and numeric mode.

Signatures:

const keypadApplicationMode: string; // DECKPAM, ESC =
const keypadNumericMode: string; // DECKPNM, ESC >
const DECKPAM: string;
const DECKPNM: string;

Character Sets (SCS)

Designate a character set into one of the G0–G3 slots, plus locking-shift constants.

Signatures:

function selectCharacterSet(gset: string, charset: string): string;
const SCS: typeof selectCharacterSet;

// G-set designators
const G0: string; // "("
const G1: string; // ")"
const G2: string; // "*"
const G3: string; // "+"

// Common charset identifiers
const DEC_SPECIAL_GRAPHICS: string; // "0"
const UNITED_KINGDOM: string; // "A"
const USASCII: string; // "B"

// Locking shifts
const LS0: string; // SI
const LS1: string; // SO
const LS1R: string;
const LS2: string;
const LS2R: string;
const LS3: string;
const LS3R: string;

Example:

import { selectCharacterSet, G0, DEC_SPECIAL_GRAPHICS, USASCII } from "@visulima/ansi/charset";

process.stdout.write(selectCharacterSet(G0, DEC_SPECIAL_GRAPHICS)); // line-drawing mode
// ...
process.stdout.write(selectCharacterSet(G0, USASCII)); // back to ASCII

Bracketed Paste

Markers a terminal emits around pasted text (CSI 200~ / CSI 201~), plus a wrap helper.

Signatures:

const bracketedPasteStart: string;
const bracketedPasteEnd: string;
function wrapBracketedPaste(text: string): string;

Focus Events

Events a terminal emits when the window gains/loses focus (DEC private mode 1004). Enable/disable reporting via enableFocusTracking / disableFocusTracking (from @visulima/ansi/mouse).

Signatures:

const FOCUS: string; // CSI I
const BLUR: string; // CSI O
const focusInEvent: string;
const focusOutEvent: string;

Graphics

Emit-only wrappers that frame already-encoded graphics payloads. They do not encode pixel/image data — the caller supplies encoded data (and, for Kitty, Base64 + chunking).

Signatures:

// Sixel: DCS aspectRatio ; backgroundMode ; gridSize q payload ST
function sixelGraphics(aspectRatio: number, backgroundMode: number, gridSize: number, payload: string): string;

// Kitty graphics: APC _G options ; payload ST
function kittyGraphics(payload: string, ...options: string[]): string;

Example:

import kittyGraphics from "@visulima/ansi/kitty-graphics";

// Transmit and display a Base64-encoded PNG already in `data`.
process.stdout.write(kittyGraphics(data, "a=T", "f=100"));

Constants

Cursor Movement

const CURSOR_UP_1: string;
const CURSOR_DOWN_1: string;
const CURSOR_FORWARD_1: string;
const CURSOR_BACKWARD_1: string;
const CURSOR_TO_COLUMN_1: string;

Screen Operations

const ALT_SCREEN_ON: string;
const ALT_SCREEN_OFF: string;
const SCROLL_UP_1: string;
const SCROLL_DOWN_1: string;

Cursor State

const SAVE_CURSOR_DEC: string;
const RESTORE_CURSOR_DEC: string;

Reset

const RESET_INITIAL_STATE: string;
const RIS: string; // Reset to Initial State

Submodule Reference

Import by Category

All functions can be imported from specific submodules:

Cursor: @visulima/ansi/cursor

import { cursorTo, cursorMove, cursorUp, cursorDown, cursorHide, cursorShow } from "@visulima/ansi/cursor";

Clear: @visulima/ansi/clear

import { clearScreen, clearScreenAndHomeCursor, resetTerminal } from "@visulima/ansi/clear";

Erase: @visulima/ansi/erase

import { eraseLine, eraseDown, eraseUp, eraseLines } from "@visulima/ansi/erase";

Hyperlink: @visulima/ansi/hyperlink

import { hyperlink } from "@visulima/ansi/hyperlink";

Image: @visulima/ansi/image

import { image } from "@visulima/ansi/image";

Strip: @visulima/ansi/strip

import { strip } from "@visulima/ansi/strip";

Other submodules: alternative-screen, scroll, title, window-ops, mouse, mode, status, iterm2, xterm, screen, passthrough, reset, background, cwd, finalterm, notification, urxvt, keypad, charset, paste, focus, sixel, kitty-graphics

Function Summary by Category

Category	Key Functions
Cursor Position	`cursorTo`, `cursorMove`, `cursorSave`, `cursorRestore`
Cursor Movement	`cursorUp`, `cursorDown`, `cursorForward`, `cursorBackward`
Cursor Visibility	`cursorHide`, `cursorShow`, `setCursorStyle`
Screen Clear	`clearScreen`, `eraseDown`, `eraseUp`
Line Erase	`eraseLine`, `eraseLineEnd`, `eraseLineStart`, `eraseLines`
Screen Buffer	`alternativeScreenOn`, `alternativeScreenOff`
Scrolling	`scrollUp`, `scrollDown`
Hyperlinks	`hyperlink`
Images	`image`
Strip	`strip`
Window	`setWindowTitle`, `maximizeWindow`, `moveWindow`
Mouse	`enableNormalMouse`, `disableNormalMouse`
Modes	`setMode`, `resetMode`
Color	`setForegroundColor`, `setBackgroundColor`, `setCursorColor`
Shell Integration	`notifyWorkingDirectory`, `finalTermPrompt`
Notifications	`notify`, `desktopNotification`, `urxvtExtension`
Keypad	`keypadApplicationMode`, `keypadNumericMode`
Character Sets	`selectCharacterSet`, `SCS`
Paste	`bracketedPasteStart`, `wrapBracketedPaste`
Focus	`FOCUS`, `BLUR`
Graphics	`sixelGraphics`, `kittyGraphics`

Terminal Support

Feature	iTerm2	Terminal.app	Windows Terminal	VS Code
Cursor Control	✅	✅	✅	✅
Screen Clearing	✅	✅	✅	✅
Alternative Screen	✅	✅	✅	✅
Hyperlinks	✅	✅	✅	✅
Images	✅	❌	❌	❌
Mouse Events	✅	✅	✅	✅
Window Ops	✅	⚠️	⚠️	❌

✅ Full support | ⚠️ Partial support | ❌ Not supported

Next Steps

Usage Guide

Learn how to use these functions with examples

Back to Overview

Return to package overview

API Reference

Usage Guide

Back to Overview

On this page

Contribute to our work and keep us going

Ready to help us out?

Submit a pull request

Good first issues