ansi-escape-sequences

What is ansi-escape-sequences?

The ansi-escape-sequences npm package provides utilities for working with ANSI escape codes, which are used to control text formatting, color, and other output options on text terminals. This package allows you to easily add color, style, and control sequences to your terminal output.

What are ansi-escape-sequences's main functionalities?

Text Formatting

This feature allows you to format text with styles such as bold, italic, underline, etc. The code sample demonstrates how to make text bold.

const ansi = require('ansi-escape-sequences');
console.log(ansi.format('This is bold text', ['bold']));

Text Coloring

This feature allows you to colorize text with various colors. The code sample demonstrates how to make text red.

const ansi = require('ansi-escape-sequences');
console.log(ansi.format('This is red text', ['red']));

Cursor Control

This feature allows you to control the cursor position in the terminal. The code sample demonstrates how to move the cursor to a specific position before printing text.

const ansi = require('ansi-escape-sequences');
process.stdout.write(ansi.cursor.goto(10, 5));
console.log('Text at position (10, 5)');

Clearing the Screen

This feature allows you to clear parts or the entire terminal screen. The code sample demonstrates how to clear the entire screen.

const ansi = require('ansi-escape-sequences');
process.stdout.write(ansi.erase.display(2));

Other packages similar to ansi-escape-sequences

chalk

Chalk is a popular library for styling terminal strings. It provides a more user-friendly API for applying styles and colors to text. Compared to ansi-escape-sequences, Chalk is more focused on ease of use and readability.

colors

Colors is another library for adding color and style to terminal output. It offers a chainable API for applying multiple styles. Compared to ansi-escape-sequences, Colors provides a more fluent interface for combining styles.

cli-color

CLI-Color is a library for styling terminal output with ANSI colors and styles. It offers a comprehensive set of features for text formatting and cursor control. Compared to ansi-escape-sequences, CLI-Color provides a more extensive set of utilities for terminal manipulation.

README

ansi-escape-sequences

A simple library containing all known terminal ansi escape codes and sequences. Useful for adding colour to your command-line output, or building a dynamic text user interface.

API Reference

Example

import ansi from 'ansi-escape-sequences'

• ansi-escape-sequences
  • .cursor
    • .hide
    • .show
    • .up([lines]) ⇒ string
    • .down([lines]) ⇒ string
    • .forward([lines]) ⇒ string
    • .back([lines]) ⇒ string
    • .nextLine([lines]) ⇒ string
    • .previousLine([lines]) ⇒ string
    • .horizontalAbsolute(n) ⇒ string
    • .position(n, m) ⇒ string
  • .erase
    • .display(n) ⇒ string
    • .inLine(n) ⇒ string
  • .style : enum
  • .rgb(r, g, b) ⇒ string
  • .bgRgb(r, g, b) ⇒ string
  • .styles(styles) ⇒ string
  • .format(str, [styleArray]) ⇒ string

ansi.cursor

cursor-related sequences

Kind: static property of ansi-escape-sequences

• .cursor
  • .hide
  • .show
  • .up([lines]) ⇒ string
  • .down([lines]) ⇒ string
  • .forward([lines]) ⇒ string
  • .back([lines]) ⇒ string
  • .nextLine([lines]) ⇒ string
  • .previousLine([lines]) ⇒ string
  • .horizontalAbsolute(n) ⇒ string
  • .position(n, m) ⇒ string

cursor.hide

Hides the cursor

Kind: static property of cursor

cursor.show

Shows the cursor

Kind: static property of cursor

cursor.up([lines]) ⇒ string

Moves the cursor lines cells up. If the cursor is already at the edge of the screen, this has no effect

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.down([lines]) ⇒ string

Moves the cursor lines cells down. If the cursor is already at the edge of the screen, this has no effect

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.forward([lines]) ⇒ string

Moves the cursor lines cells forward. If the cursor is already at the edge of the screen, this has no effect

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.back([lines]) ⇒ string

Moves the cursor lines cells back. If the cursor is already at the edge of the screen, this has no effect

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.nextLine([lines]) ⇒ string

Moves cursor to beginning of the line n lines down.

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.previousLine([lines]) ⇒ string

Moves cursor to beginning of the line n lines up.

Kind: static method of cursor

Param	Type	Default
[lines]	number	1

cursor.horizontalAbsolute(n) ⇒ string

Moves the cursor to column n.

Kind: static method of cursor

Param	Type	Description
n	number	column number

cursor.position(n, m) ⇒ string

Moves the cursor to row n, column m. The values are 1-based, and default to 1 (top left corner) if omitted.

Kind: static method of cursor

Param	Type	Description
n	number	row number
m	number	column number

ansi.erase

erase sequences

Kind: static property of ansi-escape-sequences

• .erase
  • .display(n) ⇒ string
  • .inLine(n) ⇒ string

erase.display(n) ⇒ string

Clears part of the screen. If n is 0 (or missing), clear from cursor to end of screen. If n is 1, clear from cursor to beginning of the screen. If n is 2, clear entire screen.

Kind: static method of erase

Param	Type
n	number

erase.inLine(n) ⇒ string

Erases part of the line. If n is zero (or missing), clear from cursor to the end of the line. If n is one, clear from cursor to beginning of the line. If n is two, clear entire line. Cursor position does not change.

Kind: static method of erase

Param	Type
n	number

ansi.style : enum

Various formatting styles (aka Select Graphic Rendition codes).

Kind: static enum of ansi-escape-sequences
Properties

Name	Type	Default
reset	string	"\u001b[0m"
bold	string	"\u001b[1m"
italic	string	"\u001b[3m"
underline	string	"\u001b[4m"
fontDefault	string	"\u001b[10m"
font2	string	"\u001b[11m"
font3	string	"\u001b[12m"
font4	string	"\u001b[13m"
font5	string	"\u001b[14m"
font6	string	"\u001b[15m"
imageNegative	string	"\u001b[7m"
imagePositive	string	"\u001b[27m"
black	string	"\u001b[30m"
red	string	"\u001b[31m"
green	string	"\u001b[32m"
yellow	string	"\u001b[33m"
blue	string	"\u001b[34m"
magenta	string	"\u001b[35m"
cyan	string	"\u001b[36m"
white	string	"\u001b[37m"
grey	string	"\u001b[90m"
gray	string	"\u001b[90m"
brightRed	string	"\u001b[91m"
brightGreen	string	"\u001b[92m"
brightYellow	string	"\u001b[93m"
brightBlue	string	"\u001b[94m"
brightMagenta	string	"\u001b[95m"
brightCyan	string	"\u001b[96m"
brightWhite	string	"\u001b[97m"
"bg-black"	string	"\u001b[40m"
"bg-red"	string	"\u001b[41m"
"bg-green"	string	"\u001b[42m"
"bg-yellow"	string	"\u001b[43m"
"bg-blue"	string	"\u001b[44m"
"bg-magenta"	string	"\u001b[45m"
"bg-cyan"	string	"\u001b[46m"
"bg-white"	string	"\u001b[47m"
"bg-grey"	string	"\u001b[100m"
"bg-gray"	string	"\u001b[100m"
"bg-brightRed"	string	"\u001b[101m"
"bg-brightGreen"	string	"\u001b[102m"
"bg-brightYellow"	string	"\u001b[103m"
"bg-brightBlue"	string	"\u001b[104m"
"bg-brightMagenta"	string	"\u001b[105m"
"bg-brightCyan"	string	"\u001b[106m"
"bg-brightWhite"	string	"\u001b[107m"

Example

console.log(ansi.style.red + 'this is red' + ansi.style.reset)

ansi.rgb(r, g, b) ⇒ string

Returns a 24-bit "true colour" foreground colour escape sequence.

Kind: static method of ansi-escape-sequences

Param	Type	Description
r	number	Red value.
g	number	Green value.
b	number	Blue value.

Example

> ansi.rgb(120, 0, 120)
'\u001b[38;2;120;0;120m'

ansi.bgRgb(r, g, b) ⇒ string

Returns a 24-bit "true colour" background colour escape sequence.

Kind: static method of ansi-escape-sequences

Param	Type	Description
r	number	Red value.
g	number	Green value.
b	number	Blue value.

Example

> ansi.bgRgb(120, 0, 120)
'\u001b[48;2;120;0;120m'

ansi.styles(styles) ⇒ string

Returns an ansi sequence setting one or more styles.

Kind: static method of ansi-escape-sequences

Param	Type	Description
styles	string | Array.<string>	One or more style strings.

Example

> ansi.styles('green')
'\u001b[32m'

> ansi.styles([ 'green', 'underline' ])
'\u001b[32m\u001b[4m'

> ansi.styles([ 'bg-red', 'rgb(200,200,200)' ])
'\u001b[41m\u001b[38;2;200;200;200m'

ansi.format(str, [styleArray]) ⇒ string

A convenience function, applying the styles provided in styleArray to the input string.

Partial, inline styling can also be applied using the syntax [style-list]{text to format} anywhere within the input string, where style-list is a space-separated list of styles from ansi.style. For example [bold white bg-red]{bold white text on a red background}.

24-bit "true colour" values can be set using rgb(n,n,n) syntax (no spaces), for example [rgb(255,128,0) underline]{orange underlined}. Background 24-bit colours can be set using bg-rgb(n,n,n) syntax.

Kind: static method of ansi-escape-sequences

Param	Type	Description
str	string	The string to format. Can also include inline-formatting using the syntax [style-list]{text to format} anywhere within the string.
[styleArray]	string | Array.<string>	One or more style strings to apply to the input string. Valid strings are any property from the ansi.style object (e.g. red or bg-red), rgb(n,n,n) or bg-rgb(n,n,n).

Example

> ansi.format('what?', 'green')
'\u001b[32mwhat?\u001b[0m'

> ansi.format('what?', ['green', 'bold'])
'\u001b[32m\u001b[1mwhat?\u001b[0m'

> ansi.format('something', ['rgb(255,128,0)', 'bold'])
'\u001b[38;2;255;128;0m\u001b[1msomething\u001b[0m'

> ansi.format('Inline styling: [rgb(255,128,0) bold]{something}')
'Inline styling: \u001b[38;2;255;128;0m\u001b[1msomething\u001b[0m'

> ansi.format('Inline styling: [bg-rgb(255,128,0) bold]{something}')
'Inline styling: \u001b[48;2;255;128;0m\u001b[1msomething\u001b[0m'

Load anywhere

This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.

Node.js:

const ansi = require('ansi-escape-sequences')

Within Node.js with ECMAScript Module support enabled:

import ansi from 'ansi-escape-sequences'

Within a modern browser ECMAScript Module:

import ansi from './node_modules/ansi-escape-sequences/dist/index.mjs'

---

© 2014-23 Lloyd Brookes <[e-mail]>.

Tested by test-runner. Documented by jsdoc-to-markdown.