Install

npm install @visulima/ansi

yarn add @visulima/ansi

pnpm add @visulima/ansi

Features

• Comprehensive Cursor Control: Functions for precise cursor positioning, movement, visibility, and style.
• Screen Manipulation: Clear parts of the screen or the entire screen, manage alternative screen buffers, and control scrolling.
• Text Erasure: Erase characters, lines, or parts of lines.
• iTerm2 Integration: Support for iTerm2 specific features like image display.
• Terminal Mode Management: Control various terminal modes like line feed, local echo, and mouse events.
• Mouse Event Handling: Enable and disable different types of mouse tracking.
• Window and Title Control: Manipulate window titles, icons, and basic window operations (maximize, minimize, etc. for supported terminals).
• Status Reporting: Request and report various terminal statuses.
• Hyperlinks: Create clickable hyperlinks in the terminal.
• Utility Functions: Includes functions to strip ANSI codes and passthrough sequences for tmux.

Usage

import { cursorUp, cursorLeft } from "@visulima/ansi";

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

or

import { cursorUp, cursorLeft } from "@visulima/ansi/cursor";

// etc, as above...

@visulima/ansi is ESM-only. In a CommonJS module, load it with a dynamic import():

const { cursorUp, cursorLeft } = await import("@visulima/ansi");

// etc, as above...

More Examples:

Cursor Manipulation

import { cursorTo, cursorUp, eraseLine } from "@visulima/ansi";

// Move cursor to column 10, row 5
process.stdout.write(cursorTo(10, 5));

// Move cursor up 3 lines
process.stdout.write(cursorUp(3));

// Erase the current line
process.stdout.write(eraseLine);

Screen Clearing

import { clearScreenAndHomeCursor, eraseDown } from "@visulima/ansi";

// Clear the entire screen and move the cursor to the top-left
process.stdout.write(clearScreenAndHomeCursor);

// Clear from cursor to end of screen
process.stdout.write(eraseDown);

Text Styling (with other libraries)

While @visulima/ansi focuses on terminal control, you can combine it with libraries like chalk for text styling:

import { cursorTo } from "@visulima/ansi";
import chalk from "chalk";

process.stdout.write(cursorTo(0, 0));
process.stdout.write(chalk.blue("This is a blue message at the top left!"));

API

This package exports the following functions and constants. For a detailed list of all exports, see the src/index.ts file.

General

• beep

Alternative Screen (from alternative-screen.ts)

• ALT_SCREEN_OFF
• ALT_SCREEN_ON
• alternativeScreenOff
• alternativeScreenOn

Clear (from clear.ts)

• clearLineAndHomeCursor
• clearScreenAndHomeCursor
• clearScreenFromTopLeft
• resetTerminal

Clipboard (from clipboard.ts)

• setClipboard — write text to the terminal clipboard via OSC 52 (works over SSH/tmux)
• requestClipboard — request the clipboard contents
• clearClipboard — clear a clipboard selection
• ClipboardSelection (type)

Constants (from constants.ts)

• ESC, CSI, OSC, BEL, SEP, DCS, ST, APC, SOS, PM — low-level sequence primitives for composing custom escape sequences

Cursor (from cursor.ts)

• CURSOR_BACKWARD_1
• CURSOR_DOWN_1
• CURSOR_FORWARD_1
• CURSOR_UP_1
• cursorBackward
• cursorBackwardTab
• cursorDown
• cursorForward
• cursorHide
• cursorHorizontalAbsolute
• cursorHorizontalForwardTab
• cursorLeft
• cursorMove
• cursorNextLine
• cursorPosition
• cursorPreviousLine
• cursorRestore
• cursorSave
• cursorShow
• cursorTo
• cursorToColumn1
• cursorUp
• cursorVerticalAbsolute
• eraseCharacter (Note: Also related to erase)
• REQUEST_CURSOR_POSITION
• REQUEST_EXTENDED_CURSOR_POSITION
• RESTORE_CURSOR_DEC
• SAVE_CURSOR_DEC
• setCursorStyle

Erase (from erase.ts)

• eraseDisplay
• eraseDown
• eraseInLine
• eraseLine
• eraseLineEnd
• eraseLines
• eraseLineStart
• eraseScreen
• eraseScreenAndScrollback
• eraseUp

Hyperlink (from hyperlink.ts)

• hyperlink

Image (from image.ts)

• image

iTerm2 Integration (from iterm2.ts and iterm2/)

• IT2_AUTO
• it2Cells
• it2Percent
• it2Pixels
• iTerm2
• ITerm2File
• ITerm2FileEnd
• ITerm2FilePart
• ITerm2MultipartFileStart

Mode (from mode.ts)

• BDSM
• BiDirectionalSupportMode
• createAnsiMode
• createDecMode
• DECRPM
• DECRQM
• InsertReplaceMode
• IRM
• isModeNotRecognized
• isModePermanentlyReset
• isModePermanentlySet
• isModeReset
• isModeSet
• KAM
• KeyboardActionMode
• LineFeedNewLineMode
• LNM
• LocalEchoMode
• reportMode
• RequestBiDirectionalSupportMode
• RequestInsertReplaceMode
• RequestKeyboardActionMode
• RequestLineFeedNewLineMode
• RequestLocalEchoMode
• requestMode
• RequestSendReceiveMode
• ResetBiDirectionalSupportMode
• ResetInsertReplaceMode
• ResetKeyboardActionMode
• ResetLineFeedNewLineMode
• ResetLocalEchoMode
• resetMode
• ResetSendReceiveMode
• RM
• SendReceiveMode
• SetBiDirectionalSupportMode
• SetInsertReplaceMode
• SetKeyboardActionMode
• SetLineFeedNewLineMode
• SetLocalEchoMode
• setMode
• SetSendReceiveMode
• SM
• SRM

Mouse (from mouse.ts)

• disableAnyEventMouse
• disableButtonEventMouse
• disableFocusTracking
• disableNormalMouse
• disableSgrMouse
• disableX10Mouse
• enableAnyEventMouse
• enableButtonEventMouse
• enableFocusTracking
• enableNormalMouse
• enableSgrMouse
• enableX10Mouse
• encodeMouseButtonByte
• MouseButton
• mouseSgrSequence
• mouseX10Sequence

Passthrough (from passthrough.ts)

• SCREEN_MAX_LEN_DEFAULT
• SCREEN_TYPICAL_LIMIT
• screenPassthrough
• tmuxPassthrough

Progress (from progress.ts)

• resetProgressBar
• setProgressBar
• setErrorProgressBar
• setIndeterminateProgressBar
• setWarningProgressBar

Reset (from reset.ts)

• RESET_INITIAL_STATE
• RIS

Screen (from screen.ts)

• clearTabStop
• deleteCharacter
• deleteLine
• insertCharacter
• insertLine
• repeatPreviousCharacter
• requestPresentationStateReport
• setLeftRightMargins
• setTopBottomMargins

Scroll (from scroll.ts)

• SCROLL_DOWN_1
• SCROLL_UP_1
• scrollDown
• scrollUp

Status (from status.ts)

• CPR
• createAnsiStatusReport
• createDecStatusReport
• cursorPositionReport
• DA1
• DA2
• DA3
• DECXCPR
• deviceStatusReport
• DSR
• DSR_KeyboardLanguageDEC
• DSR_PrinterStatusDEC
• DSR_TerminalStatus
• DSR_UDKStatusDEC
• extendedCursorPositionReport
• reportKeyboardLanguageDEC
• reportPrimaryDeviceAttributes
• reportPrinterNoPaperDEC
• reportPrinterNotReadyDEC
• reportPrinterReadyDEC
• reportSecondaryDeviceAttributes
• reportTerminalNotOK
• reportTerminalOK
• reportTertiaryDeviceAttributes
• reportUDKLockedDEC
• reportUDKUnlockedDEC
• requestCursorPositionReport
• requestExtendedCursorPositionReport
• requestKeyboardLanguageDEC
• RequestNameVersion
• requestPrimaryDeviceAttributes
• requestPrimaryDeviceAttributesParam0
• requestPrinterStatusDEC
• requestSecondaryDeviceAttributes
• requestSecondaryDeviceAttributesParam0
• requestTerminalStatus
• requestTertiaryDeviceAttributes
• requestTertiaryDeviceAttributesParam0
• requestUDKStatusDEC
• XTVERSION

Strip (from strip.ts)

• strip

Termcap/Terminfo (from termcap.ts)

• requestTermcap
• requestTerminfo
• XTGETTCAP

Title (from title.ts)

• decsin
• decswt
• setIconName
• setIconNameAndWindowTitle
• setIconNameAndWindowTitleWithST
• setIconNameWithST
• setWindowTitle
• setWindowTitleWithST

Window Operations (from window-ops.ts)

• deiconifyWindow
• iconifyWindow
• lowerWindow
• maximizeWindow
• moveWindow
• raiseWindow
• refreshWindow
• reportWindowPosition
• reportWindowState
• requestCellSizePixels
• requestFullScreen
• requestTextAreaSizeChars
• requestTextAreaSizePixels
• requestWindowPosition
• requestWindowSizeChars
• requestWindowSizePixels
• resizeTextAreaChars
• resizeTextAreaPixels
• restoreWindow
• XTWINOPS

XTerm (from xterm.ts)

• keyModifierOptions / XTMODKEYS
• queryKeyModifierOptions / XTQMODKEYS
• setKeyModifierOptions
• resetKeyModifierOptions
• setModifyOtherKeys1
• setModifyOtherKeys2
• resetModifyOtherKeys
• queryModifyOtherKeys
• pushKittyKeyboard — push Kitty keyboard protocol flags (CSI > flags u)
• popKittyKeyboard — pop flags off the stack (CSI < n u)
• setKittyKeyboard — set flags in place (CSI = flags ; 1 u)
• queryKittyKeyboard — query current flags (CSI ? u)
• KittyKeyboardFlag — bit-flag constants
• KittyKeyboardFlags (type)

Related

• ansi-escapes - ANSI escape codes for manipulating the terminal
• sisteransi - ANSI escape codes for some terminal swag.
• console-clear - Clear the console, cross-platform

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js' release schedule. Here's a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• Daniel Bannert
• All Contributors

Made with ❤️ at Anolilab

This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Anolilab is a Development and AI Studio. Contact us at [email protected] if you need any help with these technologies or just want to say hi!

License

The visulima ansi is open-sourced software licensed under the MIT