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