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
``js
import ansi from 'ansi-escape-sequences'
`

* ansi-escape-sequences
* .cursor
* .hide
* .show
* [.up([lines])](#module_ansi-escape-sequences.cursor.up) ⇒ string
* [.down([lines])](#module_ansi-escape-sequences.cursor.down) ⇒ string
* [.forward([lines])](#module_ansi-escape-sequences.cursor.forward) ⇒ string
* [.back([lines])](#module_ansi-escape-sequences.cursor.back) ⇒ string
* [.nextLine([lines])](#module_ansi-escape-sequences.cursor.nextLine) ⇒ string
* [.previousLine([lines])](#module_ansi-escape-sequences.cursor.previousLine) ⇒ 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])](#module_ansi-escape-sequences.format) ⇒ string

ansi.cursor

cursor-related sequences

Kind: static property of ansi-escape-sequences

* .cursor
* .hide
* .show
* [.up([lines])](#module_ansi-escape-sequences.cursor.up) ⇒ string
* [.down([lines])](#module_ansi-escape-sequences.cursor.down) ⇒ string
* [.forward([lines])](#module_ansi-escape-sequences.cursor.forward) ⇒ string
* [.back([lines])](#module_ansi-escape-sequences.cursor.back) ⇒ string
* [.nextLine([lines])](#module_ansi-escape-sequences.cursor.nextLine) ⇒ string
* [.previousLine([lines])](#module_ansi-escape-sequences.cursor.previousLine) ⇒ string
* .horizontalAbsolute(n) ⇒ string
* .position(n, m) ⇒ string

$3

Hides the cursor

Kind: static property of cursor

$3

Shows the cursor

Kind: static property of cursor

$3

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 |

$3

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 |

$3

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 |

$3

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 |

$3

Moves cursor to beginning of the line n lines down.

Kind: static method of cursor

| Param | Type | Default |
| --- | --- | --- |
| [lines] | number | 1 |

$3

Moves cursor to beginning of the line n lines up.

Kind: static method of cursor

| Param | Type | Default |
| --- | --- | --- |
| [lines] | number | 1 |

$3

Moves the cursor to column n.

Kind: static method of cursor

| Param | Type | Description |
| --- | --- | --- |
| n | number | column number |

$3

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

$3

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 |

$3

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 | "\u001b0m" |
| 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
`js
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
`js
> ansi.rgb(120, 0, 120)
'\u001b38;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
`js
> ansi.bgRgb(120, 0, 120)
'\u001b48;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
`js
> 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
`js
> 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: \u001b48;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:

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

Within Node.js with ECMAScript Module support enabled:

`js
import ansi from 'ansi-escape-sequences'
`

Within a modern browser ECMAScript Module:

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

*

© 2014-25 Lloyd Brookes \.

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