[](https://www.npmjs.org/package/ansi-escape-sequences)
[](https://www.npmjs.org/package/ansi-escape-sequences)
[](https://travis-ci.org/75lb/ansi-escape-sequences)
[](https://david-dm.org/75lb/ansi-escape-sequences)
[](https://github.com/feross/standard)

# ansi-escape-sequences
A simple library containing all known terminal [ansi escape codes and sequences](http://en.wikipedia.org/wiki/ANSI_escape_code). Useful for adding colour to your command-line output, or building a dynamic text user interface.

## API Reference
**Example**
```js
const ansi = require('ansi-escape-sequences')
```

* [ansi-escape-sequences](#module_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) ⇒ 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)](#module_ansi-escape-sequences.cursor.horizontalAbsolute) ⇒ string
* [.position(n, m)](#module_ansi-escape-sequences.cursor.position) ⇒ string
* [.erase](#module_ansi-escape-sequences.erase)
* [.display(n)](#module_ansi-escape-sequences.erase.display) ⇒ string
* [.inLine(n)](#module_ansi-escape-sequences.erase.inLine) ⇒ string
* [.style](#module_ansi-escape-sequences.style) : enum
* [.styles(effectArray)](#module_ansi-escape-sequences.styles) ⇒ string
* [.format(str, [styleArray])](#module_ansi-escape-sequences.format) ⇒ string



## ansi.cursor
cursor-related sequences

**Kind**: static property of [ansi-escape-sequences](#module_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) ⇒ 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)](#module_ansi-escape-sequences.cursor.horizontalAbsolute) ⇒ string
* [.position(n, m)](#module_ansi-escape-sequences.cursor.position) ⇒ string



### cursor.hide
Hides the cursor

**Kind**: static property of [cursor](#module_ansi-escape-sequences.cursor)


### cursor.show
Shows the cursor

**Kind**: static property of [cursor](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.cursor)

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



### cursor.horizontalAbsolute(n) ⇒ string
Moves the cursor to column n.

**Kind**: static method of [cursor](#module_ansi-escape-sequences.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](#module_ansi-escape-sequences.cursor)

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



## ansi.erase
erase sequences

**Kind**: static property of [ansi-escape-sequences](#module_ansi-escape-sequences)

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

| Param | Type |
| --- | --- |
| n | number |



## ansi.style : enum
Various formatting styles (aka Select Graphic Rendition codes).

**Kind**: static enum of [ansi-escape-sequences](#module_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" |
| "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" |

**Example**
```js
console.log(ansi.style.red + 'this is red' + ansi.style.reset)
```


## ansi.styles(effectArray) ⇒ string
Returns an ansi sequence setting one or more effects

**Kind**: static method of [ansi-escape-sequences](#module_ansi-escape-sequences)

| Param | Type | Description |
| --- | --- | --- |
| effectArray | string \| Array.<string> | a style, or list or styles |

**Example**
```js
> ansi.styles('green')
'\u001b[32m'

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


## ansi.format(str, [styleArray]) ⇒ string
A convenience function, applying the provided styles to the input string and then resetting.

Inline styling can be applied using the syntax `[style-list]{text to format}`, where `style-list` is a space-separated list of styles from [ansi.style](#module_ansi-escape-sequences.style). For example `[bold white bg-red]{bold white text on a red background}`.

**Kind**: static method of [ansi-escape-sequences](#module_ansi-escape-sequences)

| Param | Type | Description |
| --- | --- | --- |
| str | string | the string to format |
| [styleArray] | Array.<string> | a list of styles to add to the input string |

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

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

> ansi.format('[green bold]{what?}')
'\u001b[32;1mwhat?\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'
```

Old browser (adds `window.ansi`):

```html

```

* * *

© 2014-19 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).