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"));

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

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`

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