ansi-escape-sequences

A simple library containing all known terminal ansi escape codes and sequences.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
ansi-escape-sequences
6406.2.2a year ago10 years agoMinified + gzip package size for ansi-escape-sequences in KB

Readme

view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI js-standard-style
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'

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

ansi.cursor

cursor-related sequences
Kind: static property of ansi-escape-sequences
* [.hide](#module_ansi-escape-sequences.cursor.hide)
* [.show](#module_ansi-escape-sequences.cursor.show)
* [.up([lines])](#module_ansi-escape-sequences.cursor.up) ⇒ <code>string</code>
* [.down([lines])](#module_ansi-escape-sequences.cursor.down) ⇒ <code>string</code>
* [.forward([lines])](#module_ansi-escape-sequences.cursor.forward) ⇒ <code>string</code>
* [.back([lines])](#module_ansi-escape-sequences.cursor.back) ⇒ <code>string</code>
* [.nextLine([lines])](#module_ansi-escape-sequences.cursor.nextLine) ⇒ <code>string</code>
* [.previousLine([lines])](#module_ansi-escape-sequences.cursor.previousLine) ⇒ <code>string</code>
* [.horizontalAbsolute(n)](#module_ansi-escape-sequences.cursor.horizontalAbsolute) ⇒ <code>string</code>
* [.position(n, m)](#module_ansi-escape-sequences.cursor.position) ⇒ <code>string</code>

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
* [.display(n)](#module_ansi-escape-sequences.erase.display) ⇒ <code>string</code>
* [.inLine(n)](#module_ansi-escape-sequences.erase.inLine) ⇒ <code>string</code>

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 | "\u001b0m" | | bold | string | "\u001b1m" | | italic | string | "\u001b3m" | | underline | string | "\u001b4m" | | fontDefault | string | "\u001b10m" | | font2 | string | "\u001b11m" | | font3 | string | "\u001b12m" | | font4 | string | "\u001b13m" | | font5 | string | "\u001b14m" | | font6 | string | "\u001b15m" | | imageNegative | string | "\u001b7m" | | imagePositive | string | "\u001b27m" | | black | string | "\u001b30m" | | red | string | "\u001b31m" | | green | string | "\u001b32m" | | yellow | string | "\u001b33m" | | blue | string | "\u001b34m" | | magenta | string | "\u001b35m" | | cyan | string | "\u001b36m" | | white | string | "\u001b37m" | | grey | string | "\u001b90m" | | gray | string | "\u001b90m" | | brightRed | string | "\u001b91m" | | brightGreen | string | "\u001b92m" | | brightYellow | string | "\u001b93m" | | brightBlue | string | "\u001b94m" | | brightMagenta | string | "\u001b95m" | | brightCyan | string | "\u001b96m" | | brightWhite | string | "\u001b97m" | | "bg-black" | string | "\u001b40m" | | "bg-red" | string | "\u001b41m" | | "bg-green" | string | "\u001b42m" | | "bg-yellow" | string | "\u001b43m" | | "bg-blue" | string | "\u001b44m" | | "bg-magenta" | string | "\u001b45m" | | "bg-cyan" | string | "\u001b46m" | | "bg-white" | string | "\u001b47m" | | "bg-grey" | string | "\u001b100m" | | "bg-gray" | string | "\u001b100m" | | "bg-brightRed" | string | "\u001b101m" | | "bg-brightGreen" | string | "\u001b102m" | | "bg-brightYellow" | string | "\u001b103m" | | "bg-brightBlue" | string | "\u001b104m" | | "bg-brightMagenta" | string | "\u001b105m" | | "bg-brightCyan" | string | "\u001b106m" | | "bg-brightWhite" | string | "\u001b107m" |
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 \<75pound@gmail.com\>.
Tested by test-runner. Documented by jsdoc-to-markdown.